Menus

getCommand

Returns: Command

Show code

    MenuItem.prototype.getCommand = function () {
        return this._command;
    };

getParentMenu

Returns: Menu

Show code

    MenuItem.prototype.getParentMenu = function () {
        var parent = $(_getHTMLMenuItem(this.id)).parents(".dropdown").get(0);
        if (!parent) {
            return null;
        }

        return getMenu(parent.id);
    };

addMenuDivider

position nullable string

constant defining the position of new the divider relative to other MenuItems. Default is LAST. (see Insertion position constants).

relativeID nullable string

id of menuItem, sub-menu, or menu section that the new divider will be positioned relative to. Required for all position constants except FIRST and LAST

Returns: MenuItem

the newly created divider

Show code

    Menu.prototype.addMenuDivider = function (position, relativeID) {
        return this.addMenuItem(DIVIDER, "", position, relativeID);
    };

addMenuItem

command non-nullable string, Command

the command the menu will execute. Pass Menus.DIVIDER for a menu divider, or just call addMenuDivider() instead.

keyBindings nullable string, Array.<{key: string, platform: string}>

register one one or more key bindings to associate with the supplied command.

position nullable string

constant defining the position of new MenuItem relative to other MenuItems. Values: - With no relativeID, use Menus.FIRST or LAST (default is LAST) - Relative to a command id, use BEFORE or AFTER (required) - Relative to a MenuSection, use FIRST_IN_SECTION or LAST_IN_SECTION (required)

relativeID nullable string

command id OR one of the MenuSection.* constants. Required for all position constants except FIRST and LAST.

Returns: MenuItem

the newly created MenuItem

Show code

    Menu.prototype.addMenuItem = function (command, keyBindings, position, relativeID) {
        var menuID = this.id,
            id,
            $menuItem,
            menuItem,
            name,
            commandID;

        if (!command) {
            console.error("addMenuItem(): missing required parameters: command");
            return null;
        }

        if (typeof (command) === "string") {
            if (command === DIVIDER) {
                name = DIVIDER;
                commandID = _getNextMenuItemDividerID();
            } else {
                commandID = command;
                command = CommandManager.get(commandID);
                if (!command) {
                    console.error("addMenuItem(): commandID not found: " + commandID);
                    return null;
                }
                name = command.getName();
            }
        } else {
            commandID = command.getID();
            name = command.getName();
        }

        // Internal id is the a composite of the parent menu id and the command id.
        id = this._getMenuItemId(commandID);

        if (menuItemMap[id]) {
            console.log("MenuItem added with same id of existing MenuItem: " + id);
            return null;
        }

        // create MenuItem
        menuItem = new MenuItem(id, command);
        menuItemMap[id] = menuItem;

        // create MenuItem DOM
        if (_isHTMLMenu(this.id)) {
            if (name === DIVIDER) {
                $menuItem = $("<li><hr class='divider' id='" + id + "' /></li>");
            } else {
                // Create the HTML Menu
                $menuItem = $("<li><a href='#' id='" + id + "'> <span class='menu-name'></span></a></li>");

                $menuItem.on("click", function () {
                    menuItem._command.execute();
                });

                var self = this;
                $menuItem.on("mouseenter", function () {
                    self.closeSubMenu();
                });
            }

            // Insert menu item
            var $relativeElement = this._getRelativeMenuItem(relativeID, position);
            _insertInList($("li#" + StringUtils.jQueryIdEscape(this.id) + " > ul.dropdown-menu"),
                          $menuItem, position, $relativeElement);
        } else {
            var bindings = KeyBindingManager.getKeyBindings(commandID),
                binding,
                bindingStr = "",
                displayStr = "";

            if (bindings && bindings.length > 0) {
                binding = bindings[bindings.length - 1];
                bindingStr = binding.displayKey || binding.key;
            }

            if (bindingStr.length > 0) {
                displayStr = KeyBindingManager.formatKeyDescriptor(bindingStr);
            }

            if (position === FIRST_IN_SECTION || position === LAST_IN_SECTION) {
                if (!relativeID.hasOwnProperty("sectionMarker")) {
                    console.error("Bad Parameter in _getRelativeMenuItem(): relativeID must be a MenuSection when position refers to a menu section");
                    return null;
                }

                // For sections, pass in the marker for that section.
                relativeID = relativeID.sectionMarker;
            }

            brackets.app.addMenuItem(this.id, name, commandID, bindingStr, displayStr, position, relativeID, function (err) {
                switch (err) {
                case NO_ERROR:
                    break;
                case ERR_INVALID_PARAMS:
                    console.error("addMenuItem(): Invalid Parameters when adding the command " + commandID);
                    break;
                case ERR_NOT_FOUND:
                    console.error("_getRelativeMenuItem(): MenuItem with Command id " + relativeID + " not found in the Menu " + menuID);
                    break;
                default:
                    console.error("addMenuItem(); Unknown Error (" + err + ") when adding the command " + commandID);
                }
            });
            menuItem.isNative = true;
        }

        // Initialize MenuItem state
        if (menuItem.isDivider) {
            menuItem.dividerId = commandID;
        } else {
            if (keyBindings) {
                // Add key bindings. The MenuItem listens to the Command object to update MenuItem DOM with shortcuts.
                if (!Array.isArray(keyBindings)) {
                    keyBindings = [keyBindings];
                }
            }

            // Note that keyBindings passed during MenuItem creation take precedent over any existing key bindings
            KeyBindingManager.addBinding(commandID, keyBindings);

            // Look for existing key bindings
            _addExistingKeyBinding(menuItem);

            menuItem._checkedChanged();
            menuItem._enabledChanged();
            menuItem._nameChanged();
        }

        return menuItem;
    };

addSubMenu

name non-nullable string

displayed in menu item of the submenu

id non-nullable string

position nullable string

constant defining the position of new MenuItem of the submenu relative to other MenuItems. Values: - With no relativeID, use Menus.FIRST or LAST (default is LAST) - Relative to a command id, use BEFORE or AFTER (required) - Relative to a MenuSection, use FIRST_IN_SECTION or LAST_IN_SECTION (required)

relativeID nullable string

command id OR one of the MenuSection.* constants. Required for all position constants except FIRST and LAST.

Returns: Menu

the newly created submenu

Show code

    Menu.prototype.addSubMenu = function (name, id, position, relativeID) {

        if (!name || !id) {
            console.error("addSubMenu(): missing required parameters: name and id");
            return null;
        }

        // Guard against duplicate context menu ids
        if (contextMenuMap[id]) {
            console.log("Context menu added with id of existing Context Menu: " + id);
            return null;
        }

        var menu = new ContextMenu(id);
        contextMenuMap[id] = menu;

        var menuItemID = this.id + "-" + id;

        if (menuItemMap[menuItemID]) {
            console.log("MenuItem added with same id of existing MenuItem: " + id);
            return null;
        }

        // create MenuItem
        var menuItem = new MenuItem(menuItemID, SUBMENU);
        menuItemMap[menuItemID] = menuItem;

        menu.parentMenuItem = menuItem;

        // create MenuItem DOM
        if (_isHTMLMenu(this.id)) {
            // Create the HTML MenuItem
            var $menuItem = $("<li><a href='#' id='" + menuItemID + "'> "   +
                             "<span class='menu-name'>" + name + "</span>" +
                             "<span style='float: right'>&rtrif;</span>"   +
                             "</a></li>");

            var self = this;
            $menuItem.on("mouseenter", function(e) {
                if (self.openSubMenu && self.openSubMenu.id === menu.id) {
                    return;
                }
                self.closeSubMenu();
                self.openSubMenu = menu;
                menu.open();
            });

            // Insert menu item
            var $relativeElement = this._getRelativeMenuItem(relativeID, position);
            _insertInList($("li#" + StringUtils.jQueryIdEscape(this.id) + " > ul.dropdown-menu"),
            $menuItem, position, $relativeElement);
        } else {
            // TODO: add submenus for native menus
        }
        return menu;
    };

closeSubMenu

Show code

    Menu.prototype.closeSubMenu = function() {
        if (this.openSubMenu) {
            this.openSubMenu.close();
            this.openSubMenu = null;
        }
    };

removeMenuDivider

menuItemID non-nullable string

the menu item id of the divider to remove.

Show code

    Menu.prototype.removeMenuDivider = function (menuItemID) {
        var menuItem,
            $HTMLMenuItem;

        if (!menuItemID) {
            console.error("removeMenuDivider(): missing required parameters: menuItemID");
            return;
        }

        menuItem = getMenuItem(menuItemID);

        if (!menuItem) {
            console.error("removeMenuDivider(): parameter menuItemID: %s is not a valid menu item id", menuItemID);
            return;
        }

        if (!menuItem.isDivider) {
            console.error("removeMenuDivider(): parameter menuItemID: %s is not a menu divider", menuItemID);
            return;
        }

        if (_isHTMLMenu(this.id)) {
            // Targeting parent to get the menu divider <hr> and the <li> that contains it
            $HTMLMenuItem = $(_getHTMLMenuItem(menuItemID)).parent();
            if ($HTMLMenuItem) {
                $HTMLMenuItem.remove();
            } else {
                console.error("removeMenuDivider(): HTML menu divider not found: %s", menuItemID);
                return;
            }
        } else {
            brackets.app.removeMenuItem(menuItem.dividerId, function (err) {
                if (err) {
                    console.error("removeMenuDivider() -- divider not found: %s (error: %s)", menuItemID, err);
                }
            });
        }

        if (!menuItemMap[menuItemID]) {
            console.error("removeMenuDivider(): menu divider not found in menuItemMap: %s", menuItemID);
            return;
        }

        delete menuItemMap[menuItemID];
    };

removeMenuItem

command non-nullable string, Command

command the menu would execute if we weren't deleting it.

Show code

    Menu.prototype.removeMenuItem = function (command) {
        var menuItemID,
            commandID;

        if (!command) {
            console.error("removeMenuItem(): missing required parameters: command");
            return;
        }

        if (typeof (command) === "string") {
            var commandObj = CommandManager.get(command);
            if (!commandObj) {
                console.error("removeMenuItem(): command not found: " + command);
                return;
            }
            commandID = command;
        } else {
            commandID = command.getID();
        }
        menuItemID = this._getMenuItemId(commandID);

        var menuItem = getMenuItem(menuItemID);
        removeMenuItemEventListeners(menuItem);

        if (_isHTMLMenu(this.id)) {
            // Targeting parent to get the menu item <a> and the <li> that contains it
            $(_getHTMLMenuItem(menuItemID)).parent().remove();
        } else {
            brackets.app.removeMenuItem(commandID, function (err) {
                if (err) {
                    console.error("removeMenuItem() -- command not found: " + commandID + " (error: " + err + ")");
                }
            });
        }

        delete menuItemMap[menuItemID];
    };

removeSubMenu

subMenuID non-nullable string

the menu id of the submenu to remove.

Show code

    Menu.prototype.removeSubMenu = function (subMenuID) {
        var subMenu,
            parentMenuItem,
            commandID = "";

        if (!subMenuID) {
            console.error("removeSubMenu(): missing required parameters: subMenuID");
            return;
        }

        subMenu = getContextMenu(subMenuID);

        if (!subMenu || !subMenu.parentMenuItem) {
            console.error("removeSubMenu(): parameter subMenuID: %s is not a valid submenu id", subMenuID);
            return;
        }

        parentMenuItem = subMenu.parentMenuItem;


        if (!menuItemMap[parentMenuItem.id]) {
            console.error("removeSubMenu(): parent menuItem not found in menuItemMap: %s", parentMenuItem.id);
            return;
        }

        // Remove all of the menu items in the submenu
        _.forEach(menuItemMap, function (value, key) {
            if (_.startsWith(key, subMenuID)) {
                if (value.isDivider) {
                    subMenu.removeMenuDivider(key);
                } else {
                    commandID = value.getCommand();
                    subMenu.removeMenuItem(commandID);
                }
            }
        });

        if (_isHTMLMenu(this.id)) {
            $(_getHTMLMenuItem(parentMenuItem.id)).parent().remove(); // remove the menu item
            $(_getHTMLMenu(subMenuID)).remove(); // remove the menu
        } else {
            // TODO: remove submenus for native menus
        }


        delete menuItemMap[parentMenuItem.id];
        delete contextMenuMap[subMenuID];
    };

assignContextMenuToSelector STATIC

Show code

    ContextMenu.assignContextMenuToSelector = function (selector, cmenu) {
        $(selector).on("click", function (e) {
            var buttonOffset,
                buttonHeight;

            e.stopPropagation();

            if (cmenu.isOpen()) {
                cmenu.close();
            } else {
                buttonOffset = $(this).offset();
                buttonHeight = $(this).outerHeight();
                cmenu.open({
                    pageX: buttonOffset.left,
                    pageY: buttonOffset.top + buttonHeight
                });
            }
        });
    };

close

Show code

    ContextMenu.prototype.close = function () {
        if (this.parentMenuItem) {
            this.trigger("beforeSubMenuClose");
        } else {
            this.trigger("beforeContextMenuClose");
        }
        this.closeSubMenu();
        $("#" + StringUtils.jQueryIdEscape(this.id)).removeClass("open");
    };

isOpen

Show code

    ContextMenu.prototype.isOpen = function () {
        return $("#" + StringUtils.jQueryIdEscape(this.id)).hasClass("open");
    };

open

mouseOrLocation MouseEvent,{pageX:number,pageY:number}

pass a MouseEvent to display the menu near the mouse or pass in an object with page x/y coordinates for a specific location.This paramter is not used for submenus. Submenus are always displayed at a position relative to the parent menu.

Show code

    ContextMenu.prototype.open = function (mouseOrLocation) {

        if (!this.parentMenuItem &&
           (!mouseOrLocation || !mouseOrLocation.hasOwnProperty("pageX") || !mouseOrLocation.hasOwnProperty("pageY"))) {
            console.error("ContextMenu open(): missing required parameter");
            return;
        }

        var $window = $(window),
            escapedId = StringUtils.jQueryIdEscape(this.id),
            $menuAnchor = $("#" + escapedId),
            $menuWindow = $("#" + escapedId + " > ul"),
            posTop,
            posLeft;

        // only show context menu if it has menu items
        if ($menuWindow.children().length <= 0) {
            return;
        }


        // adjust positioning so menu is not clipped off bottom or right
        if (this.parentMenuItem) { // If context menu is a submenu

            this.trigger("beforeSubMenuOpen");

            var $parentMenuItem = $(_getHTMLMenuItem(this.parentMenuItem.id));

            posTop = $parentMenuItem.offset().top;
            posLeft = $parentMenuItem.offset().left + $parentMenuItem.outerWidth();

            var elementRect = {
                top:    posTop,
                left:   posLeft,
                height: $menuWindow.height() + 25,
                width:  $menuWindow.width()
            },
            clip = ViewUtils.getElementClipSize($window, elementRect);

            if (clip.bottom > 0) {
                posTop = Math.max(0, posTop + $parentMenuItem.height() - $menuWindow.height());
            }

            posTop -= 30;   // shift top for hidden parent element
            posLeft += 3;

            if (clip.right > 0) {
                posLeft = Math.max(0, posLeft - $parentMenuItem.outerWidth() - $menuWindow.outerWidth());
            }
        } else {
            this.trigger("beforeContextMenuOpen");

            // close all other dropdowns
            closeAll();

            posTop  = mouseOrLocation.pageY;
            posLeft = mouseOrLocation.pageX;

            var elementRect = {
                top:    posTop,
                left:   posLeft,
                height: $menuWindow.height() + 25,
                width:  $menuWindow.width()
            },
            clip = ViewUtils.getElementClipSize($window, elementRect);

            if (clip.bottom > 0) {
                posTop = Math.max(0, posTop - clip.bottom);
            }
            posTop -= 30;   // shift top for hidden parent element
            posLeft += 5;


            if (clip.right > 0) {
                posLeft = Math.max(0, posLeft - clip.right);
            }
        }

        // open the context menu at final location
        $menuAnchor.addClass("open")
                   .css({"left": posLeft, "top": posTop});
    };