diff --git a/docs/API-Reference/command/CommandManager.md b/docs/API-Reference/command/CommandManager.md index 442ef9b17..7d43586a3 100644 --- a/docs/API-Reference/command/CommandManager.md +++ b/docs/API-Reference/command/CommandManager.md @@ -3,34 +3,39 @@ const CommandManager = brackets.getModule("command/CommandManager") ``` - + -## \_commands : Object -Map of all registered global commands +## EventDispatcher +Manages global application commands that can be called from menu items, key bindings, or subparts +of the application. -**Kind**: global variable -**Properties** +This module dispatches these event(s): + - commandRegistered -- when a new command is registered + - beforeExecuteCommand -- before dispatching a command -| Name | Type | Description | -| --- | --- | --- | -| commands | Object.<string, Command> | A map of command IDs to Command objects. | +**Kind**: global constant + - +## EVENT\_BEFORE\_EXECUTE\_COMMAND : string +Event triggered before command executes. -## \_commandsOriginal : Object -Temporary copy of commands map for restoring after testing TODO (issue #1039): implement separate require contexts for unit tests +**Kind**: global constant + -**Kind**: global variable -**Properties** +## SOURCE\_KEYBOARD\_SHORTCUT : string +Keyboard shortcut trigger. -| Name | Type | Description | -| --- | --- | --- | -| commands | Object.<string, Command> | A map of command IDs to Command objects. | +**Kind**: global constant + - +## SOURCE\_UI\_MENU\_CLICK : string +UI menu click trigger. -## EventDispatcher -Manages global application commands that can be called from menu items, key bindings, or subparts of the application. This module dispatches these event(s): - commandRegistered -- when a new command is registered - beforeExecuteCommand -- before dispatching a command +**Kind**: global constant + + +## SOURCE\_OTHER : string +Other trigger types. **Kind**: global constant @@ -60,18 +65,6 @@ Registers a global internal only command. | id | string | unique identifier for command. Core commands in Brackets use a simple command title as an id, for example "app.abort_quit". Extensions should use the following format: "author.myextension.mycommandname". For example, "lschmitt.csswizard.format.css". | | commandFn | function | the function to call when the command is executed. Any arguments passed to execute() (after the id) are passed as arguments to the function. If the function is asynchronous, it must return a jQuery promise that is resolved when the command completes. Otherwise, the CommandManager will assume it is synchronous, and return a promise that is already resolved. | - - -## \_testReset() -Clear all commands for unit testing, but first make copy of commands so that they can be restored afterward - -**Kind**: global function - - -## \_testRestore() -Restore original commands after test and release copy - -**Kind**: global function ## get(id) ⇒ [Command](#new_Command_new) diff --git a/docs/API-Reference/command/DefaultMenus.md b/docs/API-Reference/command/DefaultMenus.md deleted file mode 100644 index c9b497482..000000000 --- a/docs/API-Reference/command/DefaultMenus.md +++ /dev/null @@ -1,29 +0,0 @@ -### Import : -```js -const DefaultMenus = brackets.getModule("command/DefaultMenus") -``` - - - -## AppInit -Initializes the default brackets menu items. - -**Kind**: global variable - - -## \_setContextMenuItemsVisible(enabled, items) -Disables menu items present in items if enabled is true. enabled is true if file is saved and present on user system. - -**Kind**: global function - -| Param | Type | -| --- | --- | -| enabled | boolean | -| items | array | - - - -## \_setMenuItemsVisible() -Checks if file saved and present on system and disables menu items accordingly - -**Kind**: global function diff --git a/docs/API-Reference/command/Menus.md b/docs/API-Reference/command/Menus.md index a98a9bdec..a7d0967e5 100644 --- a/docs/API-Reference/command/Menus.md +++ b/docs/API-Reference/command/Menus.md @@ -434,29 +434,29 @@ Menu sections are denoted by dividers or the beginning/end of a menu | Name | Type | Default | | --- | --- | --- | -| FILE_OPEN_CLOSE_COMMANDS | string | "{\"sectionMarker\":\"\"}" | -| FILE_SAVE_COMMANDS | string | "{\"sectionMarker\":\"\"}" | -| FILE_LIVE | string | "{\"sectionMarker\":\"\"}" | -| FILE_SETTINGS | string | "{\"sectionMarker\":\"\"}" | -| FILE_EXTENSION_MANAGER | string | "{\"sectionMarker\":\"\"}" | -| EDIT_UNDO_REDO_COMMANDS | string | "{\"sectionMarker\":\"\"}" | -| EDIT_TEXT_COMMANDS | string | "{\"sectionMarker\":\"\"}" | -| EDIT_SELECTION_COMMANDS | string | "{\"sectionMarker\":\"\"}" | -| EDIT_MODIFY_SELECTION | string | "{\"sectionMarker\":\"\"}" | -| EDIT_COMMENT_SELECTION | string | "{\"sectionMarker\":\"\"}" | -| EDIT_CODE_HINTS_COMMANDS | string | "{\"sectionMarker\":\"\"}" | -| EDIT_TOGGLE_OPTIONS | string | "{\"sectionMarker\":\"\"}" | -| FIND_FIND_COMMANDS | string | "{\"sectionMarker\":\"\"}" | -| FIND_FIND_IN_COMMANDS | string | "{\"sectionMarker\":\"\"}" | -| FIND_REPLACE_COMMANDS | string | "{\"sectionMarker\":\"\"}" | -| VIEW_HIDESHOW_COMMANDS | string | "{\"sectionMarker\":\"\"}" | -| VIEW_FONTSIZE_COMMANDS | string | "{\"sectionMarker\":\"\"}" | -| VIEW_TOGGLE_OPTIONS | string | "{\"sectionMarker\":\"\"}" | -| NAVIGATE_GOTO_COMMANDS | string | "{\"sectionMarker\":\"\"}" | -| NAVIGATE_DOCUMENTS_COMMANDS | string | "{\"sectionMarker\":\"\"}" | -| NAVIGATE_OS_COMMANDS | string | "{\"sectionMarker\":\"\"}" | -| NAVIGATE_QUICK_EDIT_COMMANDS | string | "{\"sectionMarker\":\"\"}" | -| NAVIGATE_QUICK_DOCS_COMMANDS | string | "{\"sectionMarker\":\"\"}" | +| FILE_OPEN_CLOSE_COMMANDS | string | "FILE_OPEN_CLOSE_COMMANDS" | +| FILE_SAVE_COMMANDS | string | "FILE_SAVE_COMMANDS" | +| FILE_LIVE | string | "FILE_LIVE" | +| FILE_SETTINGS | string | "FILE_SETTINGS" | +| FILE_EXTENSION_MANAGER | string | "FILE_EXTENSION_MANAGER" | +| EDIT_UNDO_REDO_COMMANDS | string | "EDIT_UNDO_REDO_COMMANDS" | +| EDIT_TEXT_COMMANDS | string | "EDIT_TEXT_COMMANDS" | +| EDIT_SELECTION_COMMANDS | string | "EDIT_SELECTION_COMMANDS" | +| EDIT_MODIFY_SELECTION | string | "EDIT_MODIFY_SELECTION" | +| EDIT_COMMENT_SELECTION | string | "EDIT_COMMENT_SELECTION" | +| EDIT_CODE_HINTS_COMMANDS | string | "EDIT_CODE_HINTS_COMMANDS" | +| EDIT_TOGGLE_OPTIONS | string | "EDIT_TOGGLE_OPTIONS" | +| FIND_FIND_COMMANDS | string | "FIND_FIND_COMMANDS" | +| FIND_FIND_IN_COMMANDS | string | "FIND_FIND_IN_COMMANDS" | +| FIND_REPLACE_COMMANDS | string | "FIND_REPLACE_COMMANDS" | +| VIEW_HIDESHOW_COMMANDS | string | "VIEW_HIDESHOW_COMMANDS" | +| VIEW_FONTSIZE_COMMANDS | string | "VIEW_FONTSIZE_COMMANDS" | +| VIEW_TOGGLE_OPTIONS | string | "VIEW_TOGGLE_OPTIONS" | +| NAVIGATE_GOTO_COMMANDS | string | "NAVIGATE_GOTO_COMMANDS" | +| NAVIGATE_DOCUMENTS_COMMANDS | string | "NAVIGATE_DOCUMENTS_COMMANDS" | +| NAVIGATE_OS_COMMANDS | string | "NAVIGATE_OS_COMMANDS" | +| NAVIGATE_QUICK_EDIT_COMMANDS | string | "NAVIGATE_QUICK_EDIT_COMMANDS" | +| NAVIGATE_QUICK_DOCS_COMMANDS | string | "NAVIGATE_QUICK_DOCS_COMMANDS" | @@ -500,17 +500,6 @@ Retrieves the ContextMenu object for the corresponding id. | --- | --- | | id | string | - - -## removeMenuItemEventListeners(menuItem) -Removes the attached event listeners from the corresponding object. - -**Kind**: global function - -| Param | Type | -| --- | --- | -| menuItem | [MenuItem](#MenuItem) | - ## getMenuItem(id) ⇒ [MenuItem](#MenuItem) diff --git a/src/command/CommandManager.js b/src/command/CommandManager.js index ef8a33ab2..8171b9d2b 100644 --- a/src/command/CommandManager.js +++ b/src/command/CommandManager.js @@ -34,16 +34,36 @@ define(function (require, exports, module) { const EventDispatcher = require("utils/EventDispatcher"); + /** + * Event triggered before command executes. + * @constant {string} + */ const EVENT_BEFORE_EXECUTE_COMMAND = "beforeExecuteCommand"; - const SOURCE_KEYBOARD_SHORTCUT = "keyboardShortcut", - SOURCE_UI_MENU_CLICK = "uiMenuClick", - SOURCE_OTHER = "otherExecAction"; + + /** + * Keyboard shortcut trigger. + * @constant {string} + */ + const SOURCE_KEYBOARD_SHORTCUT = "keyboardShortcut"; + + /** + * UI menu click trigger. + * @constant {string} + */ + const SOURCE_UI_MENU_CLICK = "uiMenuClick"; + + /** + * Other trigger types. + * @constant {string} + */ + const SOURCE_OTHER = "otherExecAction"; /** * Map of all registered global commands * @type {Object} CommandMap * @property {Object.} commands - A map of command IDs to Command objects. + * @private */ let _commands = {}; @@ -52,6 +72,7 @@ define(function (require, exports, module) { * TODO (issue #1039): implement separate require contexts for unit tests * @type {Object} CommandMap * @property {Object.} commands - A map of command IDs to Command objects. + * @private */ let _commandsOriginal = {}; @@ -83,6 +104,7 @@ define(function (require, exports, module) { /** * Get command id + * @private * @return {string} */ Command.prototype.getID = function () { @@ -91,7 +113,7 @@ define(function (require, exports, module) { /** * Executes the command. Additional arguments are passed to the executing function - * + * @private * @return {$.Promise} a jQuery promise that will be resolved when the command completes. */ Command.prototype.execute = function () { @@ -120,6 +142,7 @@ define(function (require, exports, module) { /** * Is command enabled? + * @private * @return {boolean} */ Command.prototype.getEnabled = function () { @@ -129,6 +152,7 @@ define(function (require, exports, module) { /** * Sets enabled state of Command and dispatches "enabledStateChange" * when the enabled state changes. + * @private * @param {boolean} enabled */ Command.prototype.setEnabled = function (enabled) { @@ -143,6 +167,7 @@ define(function (require, exports, module) { /** * Sets enabled state of Command and dispatches "checkedStateChange" * when the enabled state changes. + * @private * @param {boolean} checked */ Command.prototype.setChecked = function (checked) { @@ -156,6 +181,7 @@ define(function (require, exports, module) { /** * Is command checked? + * @private * @return {boolean} */ Command.prototype.getChecked = function () { @@ -169,7 +195,7 @@ define(function (require, exports, module) { * Note, a Command name can appear in either HTML or native UI * so HTML tags should not be used. To add a Unicode character, * use \uXXXX instead of an HTML entity. - * + * @private * @param {string} name */ Command.prototype.setName = function (name) { @@ -183,6 +209,7 @@ define(function (require, exports, module) { /** * Get command name + * @private * @return {string} */ Command.prototype.getName = function () { @@ -259,6 +286,7 @@ define(function (require, exports, module) { /** * Clear all commands for unit testing, but first make copy of commands so that * they can be restored afterward + * @private */ function _testReset() { _commandsOriginal = _commands; @@ -267,6 +295,7 @@ define(function (require, exports, module) { /** * Restore original commands after test and release copy + * @private */ function _testRestore() { _commands = _commandsOriginal; diff --git a/src/command/DefaultMenus.js b/src/command/DefaultMenus.js index 2990acb2c..47f74c3cf 100644 --- a/src/command/DefaultMenus.js +++ b/src/command/DefaultMenus.js @@ -21,8 +21,6 @@ /*global Phoenix*/ -// @INCLUDE_IN_API_DOCS - /** * Initializes the default brackets menu items. */ diff --git a/src/command/Menus.js b/src/command/Menus.js index ee6b7dd07..9382d2a31 100644 --- a/src/command/Menus.js +++ b/src/command/Menus.js @@ -113,37 +113,65 @@ define(function (require, exports, module) { * * @enum {string} */ - let MenuSection = { - // Menu Section Command ID to mark the section - FILE_OPEN_CLOSE_COMMANDS: { sectionMarker: Commands.FILE_NEW }, - FILE_SAVE_COMMANDS: { sectionMarker: Commands.FILE_SAVE }, - FILE_LIVE: { sectionMarker: Commands.FILE_LIVE_FILE_PREVIEW }, - FILE_SETTINGS: { sectionMarker: Commands.FILE_EXTENSION_MANAGER }, - FILE_EXTENSION_MANAGER: { sectionMarker: Commands.FILE_EXTENSION_MANAGER }, // deprecated. here for legacy support - - EDIT_UNDO_REDO_COMMANDS: { sectionMarker: Commands.EDIT_UNDO }, - EDIT_TEXT_COMMANDS: { sectionMarker: Commands.EDIT_CUT }, - EDIT_SELECTION_COMMANDS: { sectionMarker: Commands.EDIT_SELECT_ALL }, - EDIT_MODIFY_SELECTION: { sectionMarker: Commands.EDIT_INDENT }, - EDIT_COMMENT_SELECTION: { sectionMarker: Commands.EDIT_LINE_COMMENT }, - EDIT_CODE_HINTS_COMMANDS: { sectionMarker: Commands.SHOW_CODE_HINTS }, - EDIT_TOGGLE_OPTIONS: { sectionMarker: Commands.TOGGLE_CLOSE_BRACKETS }, - - FIND_FIND_COMMANDS: { sectionMarker: Commands.CMD_FIND }, - FIND_FIND_IN_COMMANDS: { sectionMarker: Commands.CMD_FIND_IN_FILES }, - FIND_REPLACE_COMMANDS: { sectionMarker: Commands.CMD_REPLACE }, - - VIEW_HIDESHOW_COMMANDS: { sectionMarker: Commands.VIEW_HIDE_SIDEBAR }, - VIEW_FONTSIZE_COMMANDS: { sectionMarker: Commands.VIEW_ZOOM_SUBMENU }, - VIEW_TOGGLE_OPTIONS: { sectionMarker: Commands.TOGGLE_ACTIVE_LINE }, - - NAVIGATE_GOTO_COMMANDS: { sectionMarker: Commands.NAVIGATE_QUICK_OPEN }, - NAVIGATE_DOCUMENTS_COMMANDS: { sectionMarker: Commands.NAVIGATE_NEXT_DOC }, - NAVIGATE_OS_COMMANDS: { sectionMarker: Commands.NAVIGATE_SHOW_IN_FILE_TREE }, - NAVIGATE_QUICK_EDIT_COMMANDS: { sectionMarker: Commands.TOGGLE_QUICK_EDIT }, - NAVIGATE_QUICK_DOCS_COMMANDS: { sectionMarker: Commands.TOGGLE_QUICK_DOCS } + const MenuSection = { + FILE_OPEN_CLOSE_COMMANDS, + FILE_SAVE_COMMANDS, + FILE_LIVE, + FILE_SETTINGS, + FILE_EXTENSION_MANAGER, // Deprecated + + EDIT_UNDO_REDO_COMMANDS, + EDIT_TEXT_COMMANDS, + EDIT_SELECTION_COMMANDS, + EDIT_MODIFY_SELECTION, + EDIT_COMMENT_SELECTION, + EDIT_CODE_HINTS_COMMANDS, + EDIT_TOGGLE_OPTIONS, + + FIND_FIND_COMMANDS, + FIND_FIND_IN_COMMANDS, + FIND_REPLACE_COMMANDS, + + VIEW_HIDESHOW_COMMANDS, + VIEW_FONTSIZE_COMMANDS, + VIEW_TOGGLE_OPTIONS, + + NAVIGATE_GOTO_COMMANDS, + NAVIGATE_DOCUMENTS_COMMANDS, + NAVIGATE_OS_COMMANDS, + NAVIGATE_QUICK_EDIT_COMMANDS, + NAVIGATE_QUICK_DOCS_COMMANDS }; + // Define each section as a separate constant + const FILE_OPEN_CLOSE_COMMANDS = { sectionMarker: Commands.FILE_NEW }; + const FILE_SAVE_COMMANDS = { sectionMarker: Commands.FILE_SAVE }; + const FILE_LIVE = { sectionMarker: Commands.FILE_LIVE_FILE_PREVIEW }; + const FILE_SETTINGS = { sectionMarker: Commands.FILE_EXTENSION_MANAGER }; + const FILE_EXTENSION_MANAGER = { sectionMarker: Commands.FILE_EXTENSION_MANAGER }; // Deprecated + + const EDIT_UNDO_REDO_COMMANDS = { sectionMarker: Commands.EDIT_UNDO }; + const EDIT_TEXT_COMMANDS = { sectionMarker: Commands.EDIT_CUT }; + const EDIT_SELECTION_COMMANDS = { sectionMarker: Commands.EDIT_SELECT_ALL }; + const EDIT_MODIFY_SELECTION = { sectionMarker: Commands.EDIT_INDENT }; + const EDIT_COMMENT_SELECTION = { sectionMarker: Commands.EDIT_LINE_COMMENT }; + const EDIT_CODE_HINTS_COMMANDS = { sectionMarker: Commands.SHOW_CODE_HINTS }; + const EDIT_TOGGLE_OPTIONS = { sectionMarker: Commands.TOGGLE_CLOSE_BRACKETS }; + + const FIND_FIND_COMMANDS = { sectionMarker: Commands.CMD_FIND }; + const FIND_FIND_IN_COMMANDS = { sectionMarker: Commands.CMD_FIND_IN_FILES }; + const FIND_REPLACE_COMMANDS = { sectionMarker: Commands.CMD_REPLACE }; + + const VIEW_HIDESHOW_COMMANDS = { sectionMarker: Commands.VIEW_HIDE_SIDEBAR }; + const VIEW_FONTSIZE_COMMANDS = { sectionMarker: Commands.VIEW_ZOOM_SUBMENU }; + const VIEW_TOGGLE_OPTIONS = { sectionMarker: Commands.TOGGLE_ACTIVE_LINE }; + + const NAVIGATE_GOTO_COMMANDS = { sectionMarker: Commands.NAVIGATE_QUICK_OPEN }; + const NAVIGATE_DOCUMENTS_COMMANDS = { sectionMarker: Commands.NAVIGATE_NEXT_DOC }; + const NAVIGATE_OS_COMMANDS = { sectionMarker: Commands.NAVIGATE_SHOW_IN_FILE_TREE }; + const NAVIGATE_QUICK_EDIT_COMMANDS = { sectionMarker: Commands.TOGGLE_QUICK_EDIT }; + const NAVIGATE_QUICK_DOCS_COMMANDS = { sectionMarker: Commands.TOGGLE_QUICK_DOCS }; + /** * Insertion position constants @@ -233,6 +261,7 @@ define(function (require, exports, module) { /** * Removes the attached event listeners from the corresponding object. * @param {MenuItem} menuItem + * @private */ function removeMenuItemEventListeners(menuItem) { menuItem._command @@ -759,6 +788,7 @@ define(function (require, exports, module) { * AFTER or BEFORE, ignored when position is FIRST or LAST. * * @return {MenuItem} the newly created MenuItem + * @private */ // Menu.prototype.createMenuItemsFromJSON = function (jsonStr, position, relativeID) { // NOT IMPLEMENTED @@ -777,6 +807,7 @@ define(function (require, exports, module) { * AFTER or BEFORE, ignored when position is FIRST or LAST. * * @return {MenuItem} newly created menuItem for sub-menu + * @private */ // MenuItem.prototype.createSubMenu = function (text, id, position, relativeID) { // NOT IMPLEMENTED @@ -956,6 +987,7 @@ define(function (require, exports, module) { * NOT IMPLEMENTED * Returns the parent MenuItem if the menu item is a sub-menu, returns null otherwise. * @return {MenuItem} + * @private */ // MenuItem.prototype.getParentMenuItem = function () { // NOT IMPLEMENTED;