From a73b23f3c933fb0709662feb17a47b8093fd51e6 Mon Sep 17 00:00:00 2001 From: Pluto Date: Sat, 26 Oct 2024 00:45:31 +0530 Subject: [PATCH 1/3] docs: refine API docs for files in Command dir --- docs/API-Reference/command/CommandManager.md | 55 ++++++------ docs/API-Reference/command/DefaultMenus.md | 29 ------- docs/API-Reference/command/Menus.md | 57 +++++-------- src/command/CommandManager.js | 39 +++++++-- src/command/DefaultMenus.js | 2 - src/command/Menus.js | 90 +++++++++++++------- 6 files changed, 142 insertions(+), 130 deletions(-) delete mode 100644 docs/API-Reference/command/DefaultMenus.md diff --git a/docs/API-Reference/command/CommandManager.md b/docs/API-Reference/command/CommandManager.md index 442ef9b17d..7d43586a3b 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 c9b4974821..0000000000 --- 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 a98a9bdecc..a7d0967e51 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 ef8a33ab29..8171b9d2b7 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 2990acb2c0..47f74c3cfa 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 ee6b7dd07c..9382d2a319 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; From b40bd42d580f4b4884311ffd396d0f682be90d5b Mon Sep 17 00:00:00 2001 From: Pluto Date: Sat, 26 Oct 2024 13:09:27 +0530 Subject: [PATCH 2/3] fix: test failures --- src/command/Menus.js | 61 +++++++++++++++++++++++--------------------- 1 file changed, 32 insertions(+), 29 deletions(-) diff --git a/src/command/Menus.js b/src/command/Menus.js index 9382d2a319..6248d55213 100644 --- a/src/command/Menus.js +++ b/src/command/Menus.js @@ -100,6 +100,38 @@ define(function (require, exports, module) { const EVENT_BEFORE_SUB_MENU_CLOSE = "beforeSubMenuClose"; + + // 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 }; + + + /** * Brackets Application Menu Section Constants * It is preferred that plug-ins specify the location of new MenuItems @@ -143,35 +175,6 @@ define(function (require, exports, module) { 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 From 91227ee337a77d6d8d706fbef3c72501ec02fdfd Mon Sep 17 00:00:00 2001 From: Pluto Date: Fri, 1 Nov 2024 14:56:51 +0530 Subject: [PATCH 3/3] docs: add required files to API docs --- docs/API-Reference/command/CommandManager.md | 110 ++- docs/API-Reference/command/Commands.md | 857 ++++++++++++++++++ .../command/KeyBindingManager.md | 237 +++++ .../command/KeyboardOverlayMode.md | 43 + docs/API-Reference/command/Keys.md | 52 ++ src/command/CommandManager.js | 19 +- src/command/Commands.js | 283 +++++- src/command/KeyBindingManager.js | 208 +++-- src/command/KeyboardOverlayMode.js | 20 + src/command/Keys.js | 8 + 10 files changed, 1755 insertions(+), 82 deletions(-) create mode 100644 docs/API-Reference/command/Commands.md create mode 100644 docs/API-Reference/command/KeyBindingManager.md create mode 100644 docs/API-Reference/command/KeyboardOverlayMode.md create mode 100644 docs/API-Reference/command/Keys.md diff --git a/docs/API-Reference/command/CommandManager.md b/docs/API-Reference/command/CommandManager.md index 7d43586a3b..b2537b13af 100644 --- a/docs/API-Reference/command/CommandManager.md +++ b/docs/API-Reference/command/CommandManager.md @@ -3,6 +3,110 @@ const CommandManager = brackets.getModule("command/CommandManager") ``` + + +## Command +**Kind**: global class + +* [Command](#Command) + * [new Command(name, id, commandFn, [options])](#new_Command_new) + * [.getID()](#Command+getID) ⇒ string + * [.execute()](#Command+execute) ⇒ $.Promise + * [.getEnabled()](#Command+getEnabled) ⇒ boolean + * [.setEnabled(enabled)](#Command+setEnabled) + * [.setChecked(checked)](#Command+setChecked) + * [.getChecked()](#Command+getChecked) ⇒ boolean + * [.setName(name)](#Command+setName) + * [.getName()](#Command+getName) ⇒ string + + + +### new Command(name, id, commandFn, [options]) +Events: +- enabledStateChange +- checkedStateChange +- keyBindingAdded +- keyBindingRemoved + + +| Param | Type | Description | +| --- | --- | --- | +| name | string | text that will be displayed in the UI to represent command | +| id | string | | +| commandFn | function | the function that is called when the command is executed. TODO: where should this be triggered, The Command or Exports? | +| [options] | | | + + + +### command.getID() ⇒ string +Get command id + +**Kind**: instance method of [Command](#Command) + + +### command.execute() ⇒ $.Promise +Executes the command. Additional arguments are passed to the executing function + +**Kind**: instance method of [Command](#Command) +**Returns**: $.Promise - a jQuery promise that will be resolved when the command completes. + + +### command.getEnabled() ⇒ boolean +Is command enabled? + +**Kind**: instance method of [Command](#Command) + + +### command.setEnabled(enabled) +Sets enabled state of Command and dispatches "enabledStateChange" +when the enabled state changes. + +**Kind**: instance method of [Command](#Command) + +| Param | Type | +| --- | --- | +| enabled | boolean | + + + +### command.setChecked(checked) +Sets enabled state of Command and dispatches "checkedStateChange" +when the enabled state changes. + +**Kind**: instance method of [Command](#Command) + +| Param | Type | +| --- | --- | +| checked | boolean | + + + +### command.getChecked() ⇒ boolean +Is command checked? + +**Kind**: instance method of [Command](#Command) + + +### command.setName(name) +Sets the name of the Command and dispatches "nameChange" so that +UI that reflects the command name can update. + +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. + +**Kind**: instance method of [Command](#Command) + +| Param | Type | +| --- | --- | +| name | string | + + + +### command.getName() ⇒ string +Get command name + +**Kind**: instance method of [Command](#Command) ## EventDispatcher @@ -40,7 +144,7 @@ Other trigger types. **Kind**: global constant -## register(name, id, commandFn, [options]) ⇒ [Command](#new_Command_new) +## register(name, id, commandFn, [options]) ⇒ [Command](#Command) Registers a global command. **Kind**: global function @@ -55,7 +159,7 @@ Registers a global command. -## registerInternal(id, commandFn) ⇒ [Command](#new_Command_new) +## registerInternal(id, commandFn) ⇒ [Command](#Command) Registers a global internal only command. **Kind**: global function @@ -67,7 +171,7 @@ Registers a global internal only command. -## get(id) ⇒ [Command](#new_Command_new) +## get(id) ⇒ [Command](#Command) Retrieves a Command object by id **Kind**: global function diff --git a/docs/API-Reference/command/Commands.md b/docs/API-Reference/command/Commands.md new file mode 100644 index 0000000000..e188a3ba43 --- /dev/null +++ b/docs/API-Reference/command/Commands.md @@ -0,0 +1,857 @@ +### Import : +```js +const Commands = brackets.getModule("command/Commands") +``` + + + +## FILE\_NEW\_UNTITLED +Creates a new untitled document + +**Kind**: global variable + + +## FILE\_NEW +Creates a new file in the current project + +**Kind**: global variable + + +## FILE\_NEW\_PROJECT +Creates a new project + +**Kind**: global variable + + +## FILE\_NEW\_FOLDER +Creates a new folder in the current project + +**Kind**: global variable + + +## FILE\_DUPLICATE +Duplicates the selected file or folder + +**Kind**: global variable + + +## FILE\_DUPLICATE\_FILE +Duplicates the selected file + +**Kind**: global variable + + +## FILE\_DOWNLOAD +Downloads the selected file + +**Kind**: global variable + + +## FILE\_DOWNLOAD\_PROJECT +Downloads the entire project + +**Kind**: global variable + + +## FILE\_CUT +Cuts the selected file or folder to clipboard + +**Kind**: global variable + + +## FILE\_COPY +Copies the selected file or folder to clipboard + +**Kind**: global variable + + +## FILE\_COPY\_PATH +Copies the path of selected file or folder + +**Kind**: global variable + + +## FILE\_PASTE +Pastes file or folder from clipboard + +**Kind**: global variable + + +## FILE\_OPEN +Opens a file + +**Kind**: global variable + + +## FILE\_OPEN\_FOLDER +Opens a folder as a project + +**Kind**: global variable + + +## FILE\_SAVE +Saves the current file + +**Kind**: global variable + + +## FILE\_SAVE\_ALL +Saves all open files + +**Kind**: global variable + + +## FILE\_SAVE\_AS +Saves current file with a new name + +**Kind**: global variable + + +## FILE\_CLOSE +Closes the current file + +**Kind**: global variable + + +## FILE\_CLOSE\_ALL +Closes all open files + +**Kind**: global variable + + +## FILE\_CLOSE\_LIST +Closes files from list + +**Kind**: global variable + + +## FILE\_REOPEN\_CLOSED +Reopens last closed file + +**Kind**: global variable + + +## FILE\_OPEN\_DROPPED\_FILES +Opens files that were dropped + +**Kind**: global variable + + +## FILE\_LIVE\_FILE\_PREVIEW +Toggles live file preview + +**Kind**: global variable + + +## FILE\_LIVE\_FILE\_PREVIEW\_SETTINGS +Opens live preview settings + +**Kind**: global variable + + +## TOGGLE\_LIVE\_PREVIEW\_MB\_MODE +Toggles live preview multi-browser mode + +**Kind**: global variable + + +## CMD\_RELOAD\_LIVE\_PREVIEW +Reloads live preview + +**Kind**: global variable + + +## FILE\_LIVE\_HIGHLIGHT +Toggles live highlight + +**Kind**: global variable + + +## FILE\_PROJECT\_SETTINGS +Opens project settings + +**Kind**: global variable + + +## FILE\_RENAME +Renames selected file or folder + +**Kind**: global variable + + +## FILE\_DELETE +Deletes selected file or folder + +**Kind**: global variable + + +## FILE\_EXTENSION\_MANAGER +Opens extension manager + +**Kind**: global variable + + +## FILE\_REFRESH +Refreshes the file tree + +**Kind**: global variable + + +## FILE\_SHOW\_FOLDERS\_FIRST +Toggles show folders first in file tree + +**Kind**: global variable + + +## FILE\_OPEN\_PREFERENCES +Opens preferences + +**Kind**: global variable + + +## FILE\_OPEN\_KEYMAP +Opens keymap settings + +**Kind**: global variable + + +## FILE\_NEW\_WINDOW +Opens new window + +**Kind**: global variable + + +## FILE\_CLOSE\_WINDOW +Closes current window + +**Kind**: global variable + + +## FILE\_QUIT +Quits the application + +**Kind**: global variable + + +## EDIT\_UNDO +Undoes the last edit operation + +**Kind**: global variable + + +## EDIT\_REDO +Redoes the last undone edit operation + +**Kind**: global variable + + +## EDIT\_CUT +Cuts the selected text to clipboard + +**Kind**: global variable + + +## EDIT\_COPY +Copies the selected text to clipboard + +**Kind**: global variable + + +## EDIT\_PASTE +Pastes text from clipboard + +**Kind**: global variable + + +## EDIT\_SELECT\_ALL +Selects all text in the current document + +**Kind**: global variable + + +## EDIT\_SELECT\_LINE +Selects the current line + +**Kind**: global variable + + +## EDIT\_SPLIT\_SEL\_INTO\_LINES +Splits selection into individual lines + +**Kind**: global variable + + +## EDIT\_ADD\_CUR\_TO\_NEXT\_LINE +Adds cursor to the next line + +**Kind**: global variable + + +## EDIT\_ADD\_CUR\_TO\_PREV\_LINE +Adds cursor to the previous line + +**Kind**: global variable + + +## EDIT\_INDENT +Indents the selected text + +**Kind**: global variable + + +## EDIT\_UNINDENT +Unindents the selected text + +**Kind**: global variable + + +## EDIT\_DUPLICATE +Duplicates the selected text + +**Kind**: global variable + + +## EDIT\_DELETE\_LINES +Deletes the current line(s) + +**Kind**: global variable + + +## EDIT\_LINE\_COMMENT +Toggles line comment for current selection + +**Kind**: global variable + + +## EDIT\_BLOCK\_COMMENT +Toggles block comment for current selection + +**Kind**: global variable + + +## EDIT\_LINE\_UP +Moves current line up + +**Kind**: global variable + + +## EDIT\_LINE\_DOWN +Moves current line down + +**Kind**: global variable + + +## EDIT\_OPEN\_LINE\_ABOVE +Opens a new line above current line + +**Kind**: global variable + + +## EDIT\_OPEN\_LINE\_BELOW +Opens a new line below current line + +**Kind**: global variable + + +## TOGGLE\_CLOSE\_BRACKETS +Toggles auto close brackets + +**Kind**: global variable + + +## SHOW\_CODE\_HINTS +Shows code hints + +**Kind**: global variable + + +## EDIT\_BEAUTIFY\_CODE +Beautifies the current code + +**Kind**: global variable + + +## EDIT\_BEAUTIFY\_CODE\_ON\_SAVE +Toggles code beautification on save + +**Kind**: global variable + + +## CMD\_FIND +Opens find dialog + +**Kind**: global variable + + +## CMD\_FIND\_IN\_FILES +Opens find in files dialog + +**Kind**: global variable + + +## CMD\_FIND\_IN\_SUBTREE +Opens find in subtree dialog + +**Kind**: global variable + + +## CMD\_FIND\_NEXT +Finds next match + +**Kind**: global variable + + +## CMD\_FIND\_PREVIOUS +Finds previous match + +**Kind**: global variable + + +## CMD\_FIND\_ALL\_AND\_SELECT +Finds all matches and selects them + +**Kind**: global variable + + +## CMD\_ADD\_NEXT\_MATCH +Adds next match to selection + +**Kind**: global variable + + +## CMD\_SKIP\_CURRENT\_MATCH +Skips current match + +**Kind**: global variable + + +## CMD\_REPLACE +Replaces current match + +**Kind**: global variable + + +## CMD\_REPLACE\_IN\_FILES +Opens replace in files dialog + +**Kind**: global variable + + +## CMD\_REPLACE\_IN\_SUBTREE +Opens replace in subtree dialog + +**Kind**: global variable + + +## CMD\_FIND\_ALL\_REFERENCES +Opens find references panel + +**Kind**: global variable + + +## CMD\_THEMES\_OPEN\_SETTINGS +Opens theme settings + +**Kind**: global variable + + +## VIEW\_HIDE\_SIDEBAR +Toggles sidebar visibility + +**Kind**: global variable + + +## VIEW\_ZOOM\_IN +Zooms in the editor view + +**Kind**: global variable + + +## VIEW\_ZOOM\_OUT +Zooms out the editor view + +**Kind**: global variable + + +## VIEW\_ZOOM\_SUBMENU +Submenu for zoom options + +**Kind**: global variable + + +## VIEW\_INCREASE\_FONT\_SIZE +Increases editor font size + +**Kind**: global variable + + +## VIEW\_DECREASE\_FONT\_SIZE +Decreases editor font size + +**Kind**: global variable + + +## VIEW\_RESTORE\_FONT\_SIZE +Restores editor font size to default + +**Kind**: global variable + + +## VIEW\_SCROLL\_LINE\_UP +Scrolls editor view up by one line + +**Kind**: global variable + + +## VIEW\_SCROLL\_LINE\_DOWN +Scrolls editor view down by one line + +**Kind**: global variable + + +## VIEW\_TOGGLE\_INSPECTION +Toggles code inspection + +**Kind**: global variable + + +## VIEW\_TOGGLE\_PROBLEMS +Toggles problems panel visibility + +**Kind**: global variable + + +## TOGGLE\_LINE\_NUMBERS +Toggles line numbers visibility + +**Kind**: global variable + + +## TOGGLE\_ACTIVE\_LINE +Toggles active line highlight + +**Kind**: global variable + + +## TOGGLE\_WORD\_WRAP +Toggles word wrap + +**Kind**: global variable + + +## TOGGLE\_RULERS +Toggles rulers visibility + +**Kind**: global variable + + +## TOGGLE\_INDENT\_GUIDES +Toggles indent guides visibility + +**Kind**: global variable + + +## TOGGLE\_SEARCH\_AUTOHIDE +Toggles search auto-hide behavior + +**Kind**: global variable + + +## CMD\_OPEN +Opens a file + +**Kind**: global variable + + +## CMD\_ADD\_TO\_WORKINGSET\_AND\_OPEN +Adds file to working set and opens it + +**Kind**: global variable + + +## NAVIGATE\_NEXT\_DOC +Goes to next document + +**Kind**: global variable + + +## NAVIGATE\_PREV\_DOC +Goes to previous document + +**Kind**: global variable + + +## NAVIGATE\_NEXT\_DOC\_LIST\_ORDER +Goes to next document in list order + +**Kind**: global variable + + +## NAVIGATE\_PREV\_DOC\_LIST\_ORDER +Goes to previous document in list order + +**Kind**: global variable + + +## NAVIGATE\_SHOW\_IN\_FILE\_TREE +Shows current file in file tree + +**Kind**: global variable + + +## NAVIGATE\_SHOW\_IN\_OS +Shows current file in OS file explorer + +**Kind**: global variable + + +## NAVIGATE\_QUICK\_OPEN +Opens quick open dialog + +**Kind**: global variable + + +## NAVIGATE\_JUMPTO\_DEFINITION +Jumps to definition of symbol at cursor + +**Kind**: global variable + + +## NAVIGATE\_GOTO\_DEFINITION +Opens go to definition search + +**Kind**: global variable + + +## NAVIGATE\_GOTO\_DEFINITION\_PROJECT +Opens go to definition in project search + +**Kind**: global variable + + +## NAVIGATE\_GOTO\_LINE +Opens go to line dialog + +**Kind**: global variable + + +## NAVIGATE\_GOTO\_FIRST\_PROBLEM +Goes to first problem in current file + +**Kind**: global variable + + +## NAVIGATE\_GOTO\_NEXT\_PROBLEM +Goes to next problem in current file + +**Kind**: global variable + + +## NAVIGATE\_GOTO\_PREV\_PROBLEM +Goes to previous problem in current file + +**Kind**: global variable + + +## TOGGLE\_QUICK\_EDIT +Toggles quick edit widget + +**Kind**: global variable + + +## TOGGLE\_QUICK\_DOCS +Toggles quick docs widget + +**Kind**: global variable + + +## QUICK\_EDIT\_NEXT\_MATCH +Goes to next match in quick edit + +**Kind**: global variable + + +## QUICK\_EDIT\_PREV\_MATCH +Goes to previous match in quick edit + +**Kind**: global variable + + +## CSS\_QUICK\_EDIT\_NEW\_RULE +Creates new CSS rule in quick edit + +**Kind**: global variable + + +## HELP\_HOW\_TO\_USE\_BRACKETS +Opens how to use Brackets guide + +**Kind**: global variable + + +## HELP\_DOCS +Opens documentation + +**Kind**: global variable + + +## HELP\_SUPPORT +Opens support resources + +**Kind**: global variable + + +## HELP\_SUGGEST +Opens feature suggestion page + +**Kind**: global variable + + +## HELP\_RELEASE\_NOTES +Opens release notes + +**Kind**: global variable + + +## HELP\_GET\_INVOLVED +Opens contributor guidelines + +**Kind**: global variable + + +## HELP\_SHOW\_EXT\_FOLDER +Shows extensions folder in OS + +**Kind**: global variable + + +## HELP\_HOMEPAGE +Opens project homepage + +**Kind**: global variable + + +## HELP\_YOUTUBE +Opens YouTube channel + +**Kind**: global variable + + +## HELP\_TWITTER +Opens Twitter page + +**Kind**: global variable + + +## HELP\_TOGGLE\_SHORTCUTS\_PANEL +Toggles keyboard shortcuts panel + +**Kind**: global variable + + +## HELP\_CHECK\_UPDATES +Checks for updates + +**Kind**: global variable + + +## HELP\_AUTO\_UPDATE +Toggles auto update + +**Kind**: global variable + + +## CMD\_WORKINGSET\_SORT\_BY\_ADDED +Sorts working set by order files were added + +**Kind**: global variable + + +## CMD\_WORKINGSET\_SORT\_BY\_NAME +Sorts working set by file name + +**Kind**: global variable + + +## CMD\_WORKINGSET\_SORT\_BY\_TYPE +Sorts working set by file type + +**Kind**: global variable + + +## CMD\_WORKING\_SORT\_TOGGLE\_AUTO +Toggles automatic working set sorting + +**Kind**: global variable + + +## CMD\_KEYBOARD\_NAV\_UI\_OVERLAY +Opens keyboard navigation UI overlay + +**Kind**: global variable + + +## CMD\_SPLITVIEW\_NONE +Removes split view + +**Kind**: global variable + + +## CMD\_SPLITVIEW\_VERTICAL +Splits view vertically + +**Kind**: global variable + + +## CMD\_SPLITVIEW\_HORIZONTAL +Splits view horizontally + +**Kind**: global variable + + +## CMD\_SWITCH\_PANE\_FOCUS +Switches focus between split panes + +**Kind**: global variable + + +## HELP\_ABOUT +Shows about dialog + +**Kind**: global variable + + +## APP\_RELOAD +Reloads the application + +**Kind**: global variable + + +## APP\_RELOAD\_WITHOUT\_EXTS +Reloads the application without extensions + +**Kind**: global variable + + +## APP\_ABORT\_QUIT +Aborts application quit + +**Kind**: global variable + + +## APP\_BEFORE\_MENUPOPUP +Handler before menu popup + +**Kind**: global variable + + +## HIDE\_SIDEBAR +Hides the sidebar + +**Kind**: global variable + + +## SHOW\_SIDEBAR +Shows the sidebar + +**Kind**: global variable diff --git a/docs/API-Reference/command/KeyBindingManager.md b/docs/API-Reference/command/KeyBindingManager.md new file mode 100644 index 0000000000..496a644bd5 --- /dev/null +++ b/docs/API-Reference/command/KeyBindingManager.md @@ -0,0 +1,237 @@ +### Import : +```js +const KeyBindingManager = brackets.getModule("command/KeyBindingManager") +``` + + + +## useWindowsCompatibleBindings +Use windows-specific bindings if no other are found (e.g. Linux). +Core Brackets modules that use key bindings should always define at +least a generic keybinding that is applied for all platforms. This +setting effectively creates a compatibility mode for third party +extensions that define explicit key bindings for Windows and Mac, but +not Linux. + +**Kind**: global variable + + +## EVENT\_KEY\_BINDING\_ADDED : string +key binding add event + +**Kind**: global constant + + +## EVENT\_KEY\_BINDING\_REMOVED : string +key binding remove event + +**Kind**: global constant + + +## EVENT\_NEW\_PRESET : string +new preset event + +**Kind**: global constant + + +## EVENT\_PRESET\_CHANGED : string +preset change event + +**Kind**: global constant + + +## KEY : Object +**Kind**: global constant + + +## formatKeyDescriptor(descriptor) ⇒ string +Convert normalized key representation to display appropriate for platform. + +**Kind**: global function +**Returns**: string - Display/Operating system appropriate string + +| Param | Type | Description | +| --- | --- | --- | +| descriptor | string | Normalized key descriptor. | + + + +## removeBinding(key, [platform]) +Remove a key binding from _keymap + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| key | string | a key-description string that may or may not be normalized. | +| [platform] | string | OS from which to remove the binding (all platforms if unspecified) | + + + +## getKeymap([defaults]) ⇒ Object.<string, {commandID: string, key: string, displayKey: string}> +Returns a copy of the current key map. If the optional 'defaults' parameter is true, +then a copy of the default key map is returned. + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| [defaults] | boolean | true if the caller wants a copy of the default key map. Otherwise, the current active key map is returned. | + + + +## addBinding(command, keyBindings, platform, options) ⇒ Object \| Array.<{key: string, displayKey:String}> +Add one or more key bindings to a particular Command. + +**Kind**: global function +**Returns**: Object \| Array.<{key: string, displayKey:String}> - Returns record(s) for valid key binding(s) + +| Param | Type | Description | +| --- | --- | --- | +| command | string \| Command | A command ID or command object | +| keyBindings | Object \| Array.<{key: string, displayKey: string, platform: string}> | A single key binding or an array of keybindings. Example: "Shift-Cmd-F". Mac and Win key equivalents are automatically mapped to each other. Use displayKey property to display a different string (e.g. "CMD+" instead of "CMD="). | +| platform | string | The target OS of the keyBindings either "mac", "win" or "linux". If undefined, all platforms not explicitly defined will use the key binding. NOTE: If platform is not specified, Ctrl will be replaced by Cmd for "mac" platform | +| options | object | | +| options.isMenuShortcut | boolean | this allows alt-key shortcuts to be registered. | + + + +## getKeyBindings(command) ⇒ Array.<{{key: string, displayKey: string}}> +Retrieve key bindings currently associated with a command + +**Kind**: global function +**Returns**: Array.<{{key: string, displayKey: string}}> - An array of associated key bindings. + +| Param | Type | Description | +| --- | --- | --- | +| command | string \| Command | A command ID or command object | + + + +## getKeyBindingsDisplay(commandID) ⇒ string \| null +Retrieves the platform-specific string representation of the key bindings for a specified command. +This function is useful for displaying the keyboard shortcut associated with a given command ID to the user. +If a key binding is found for the command, it returns the formatted key descriptor. Otherwise, it returns null. + +**Kind**: global function +**Returns**: string \| null - The formatted key binding as a string if available; otherwise, null. + +| Param | Type | Description | +| --- | --- | --- | +| commandID | string | The unique identifier of the command for which the key binding is to be retrieved. | + + + +## addGlobalKeydownHook(hook) +Adds a global keydown hook that gets first crack at keydown events +before standard keybindings do. This is intended for use by modal or +semi-modal UI elements like dialogs or the code hint list that should +execute before normal command bindings are run. + +The hook is passed two parameters, the first param is the original keyboard event. +The second param is the deduced shortcut string like `Ctrl-F` if present for +that event or null if not keyboard shortcut string. If the +hook handles the event (or wants to block other global hooks from +handling the event), it should return true. Note that this will *only* +stop other global hooks and KeyBindingManager from handling the +event; to prevent further event propagation, you will need to call +stopPropagation(), stopImmediatePropagation(), and/or preventDefault() +as usual. + +Multiple keydown hooks can be registered, and are executed in order, +most-recently-added first. A keydown hook will only be added once if the same +hook is already added before. + +(We have to have a special API for this because (1) handlers are normally +called in least-recently-added order, and we want most-recently-added; +(2) native DOM events don't have a way for us to find out if +stopImmediatePropagation()/stopPropagation() has been called on the +event, so we have to have some other way for one of the hooks to +indicate that it wants to block the other hooks from running.) + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| hook | function | The global hook to add. | + + + +## removeGlobalKeydownHook(hook) +Removes a global keydown hook added by `addGlobalKeydownHook`. +Does not need to be the most recently added hook. + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| hook | function | The global hook to remove. | + + + +## registerCustomKeymapPack(packID, packName, keyMap) +This can be used by extensions to register new kepmap packs that can be listed in the keyboard shortcuts panel +under use preset dropdown. For EG. distribute a `netbeans editor` shortcuts pack via extension. + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| packID | string | A unique ID for the pack. Use `extensionID.name` format to avoid collisions. | +| packName | string | A name for the pack. | +| keyMap | Object | a keymap of the format {`Ctrl-Alt-L`: `file.liveFilePreview`} depending on the platform. The extension should decide the correct keymap based on the platform before calling this function. | + + + +## getAllCustomKeymapPacks() ⇒ Array.<Object> +Responsible to get all the custom keymap packs + +**Kind**: global function +**Returns**: Array.<Object> - an array of all the custom keymap packs, +each pack is an object with keys: `packID`, `packageName` & `keyMap` + + +## getCurrentCustomKeymapPack() ⇒ Object +To get the current custom keymap pack + +**Kind**: global function +**Returns**: Object - the current custom keymap pack + + +## resetUserShortcutsAsync() ⇒ Promise \| Promise.<void> \| \* +resets all user defined shortcuts + +**Kind**: global function + + +## isInOverlayMode() ⇒ boolean +Whether the keyboard is in overlay mode or not + +**Kind**: global function +**Returns**: boolean - True if in overlay mode else false + + +## showShortcutSelectionDialog(command) +to display the shortcut selection dialog + +**Kind**: global function + +| Param | +| --- | +| command | + + + +## canAssignBinding(commandId) ⇒ boolean +Returns true the given command id can be overriden by user. + +**Kind**: global function + +| Param | +| --- | +| commandId | + + + +## UserKeyBinding : Object +**Kind**: global typedef diff --git a/docs/API-Reference/command/KeyboardOverlayMode.md b/docs/API-Reference/command/KeyboardOverlayMode.md new file mode 100644 index 0000000000..0089932ae7 --- /dev/null +++ b/docs/API-Reference/command/KeyboardOverlayMode.md @@ -0,0 +1,43 @@ +### Import : +```js +const KeyboardOverlayMode = brackets.getModule("command/KeyboardOverlayMode") +``` + + + +## EditorManager +This handles the overlay mode + +**Kind**: global constant + + +## startOverlayMode() +Responsible to start the overlay mode + +**Kind**: global function + + +## exitOverlayMode() +Responsible to exit the overlay mode. +restores focus to previously active pane + +**Kind**: global function + + +## processOverlayKeyboardEvent(event) +Handles the keyboard navigation in overlay mode +Process the arrow keys to move between panes, Enter to select a pane, and Escape to exit overlay mode + +**Kind**: global function + +| Param | Type | +| --- | --- | +| event | KeyboardEvent | + + + +## isInOverlayMode() ⇒ boolean +to check whether in overlay mode or not + +**Kind**: global function +**Returns**: boolean - returns true if in overlay mode otherwise false diff --git a/docs/API-Reference/command/Keys.md b/docs/API-Reference/command/Keys.md new file mode 100644 index 0000000000..59cf72234a --- /dev/null +++ b/docs/API-Reference/command/Keys.md @@ -0,0 +1,52 @@ +### Import : +```js +const Keys = brackets.getModule("command/Keys") +``` + + + +## KEY : enum +Defines common keyboard key identifiers for use in keyboard event handling. + +**Kind**: global enum +**Properties** + +| Name | Type | Default | +| --- | --- | --- | +| ENTER | string | "Enter" | +| RETURN | string | "Return" | +| ESCAPE | string | "Escape" | +| ARROW_LEFT | string | "ArrowLeft" | +| ARROW_RIGHT | string | "ArrowRight" | +| ARROW_UP | string | "ArrowUp" | +| ARROW_DOWN | string | "ArrowDown" | +| SPACE | string | " " | +| TAB | string | "Tab" | +| BACKSPACE | string | "Backspace" | +| DELETE | string | "Delete" | +| HOME | string | "Home" | +| END | string | "End" | +| PAGE_UP | string | "PageUp" | +| PAGE_DOWN | string | "PageDown" | +| SHIFT | string | "Shift" | +| CONTROL | string | "Control" | +| ALT | string | "Alt" | +| META | string | "Meta" | +| F1 | string | "F1" | +| F2 | string | "F2" | +| F3 | string | "F3" | +| F4 | string | "F4" | +| F5 | string | "F5" | +| F6 | string | "F6" | +| F7 | string | "F7" | +| F8 | string | "F8" | +| F9 | string | "F9" | +| F10 | string | "F10" | +| F11 | string | "F11" | +| F12 | string | "F12" | +| INSERT | string | "Insert" | +| CONTEXT_MENU | string | "ContextMenu" | +| NUM_LOCK | string | "NumLock" | +| SCROLL_LOCK | string | "ScrollLock" | +| CAPS_LOCK | string | "CapsLock" | + diff --git a/src/command/CommandManager.js b/src/command/CommandManager.js index 8171b9d2b7..2fec64489e 100644 --- a/src/command/CommandManager.js +++ b/src/command/CommandManager.js @@ -84,7 +84,6 @@ define(function (require, exports, module) { * - keyBindingRemoved * * @constructor - * @private * @param {string} name - text that will be displayed in the UI to represent command * @param {string} id * @param {function} commandFn - the function that is called when the command is executed. @@ -104,7 +103,7 @@ define(function (require, exports, module) { /** * Get command id - * @private + * * @return {string} */ Command.prototype.getID = function () { @@ -113,7 +112,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 () { @@ -142,7 +141,7 @@ define(function (require, exports, module) { /** * Is command enabled? - * @private + * * @return {boolean} */ Command.prototype.getEnabled = function () { @@ -152,7 +151,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) { @@ -167,7 +166,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) { @@ -181,7 +180,7 @@ define(function (require, exports, module) { /** * Is command checked? - * @private + * * @return {boolean} */ Command.prototype.getChecked = function () { @@ -195,7 +194,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) { @@ -209,7 +208,7 @@ define(function (require, exports, module) { /** * Get command name - * @private + * * @return {string} */ Command.prototype.getName = function () { @@ -220,6 +219,7 @@ define(function (require, exports, module) { /** * Registers a global command. + * * @param {string} name - text that will be displayed in the UI to represent command * @param {string} id - unique identifier for command. * Core commands in Brackets use a simple command title as an id, for example "open.file". @@ -255,6 +255,7 @@ define(function (require, exports, module) { /** * Registers a global internal only command. + * * @param {string} id - 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". diff --git a/src/command/Commands.js b/src/command/Commands.js index 8e08e4a7a6..b4eb6077be 100644 --- a/src/command/Commands.js +++ b/src/command/Commands.js @@ -19,186 +19,453 @@ * */ -define(function (require, exports, module) { +// @INCLUDE_IN_API_DOCS +define(function (require, exports, module) { var DeprecationWarning = require("utils/DeprecationWarning"); - /** - * List of constants for global command IDs. - */ - - // FILE + /** Creates a new untitled document */ exports.FILE_NEW_UNTITLED = "file.newDoc"; // DocumentCommandHandlers.js handleFileNew() + + /** Creates a new file in the current project */ exports.FILE_NEW = "file.newFile"; // DocumentCommandHandlers.js handleFileNewInProject() + + /** Creates a new project */ exports.FILE_NEW_PROJECT = "file.newProject"; // Phoenix extension: new-project.js + + /** Creates a new folder in the current project */ exports.FILE_NEW_FOLDER = "file.newFolder"; // DocumentCommandHandlers.js handleNewFolderInProject() + + /** Duplicates the selected file or folder */ exports.FILE_DUPLICATE = "file.duplicate"; // ProjectManager.js + + /** Duplicates the selected file */ exports.FILE_DUPLICATE_FILE = "file.duplicateFile"; // ProjectManager.js + + /** Downloads the selected file */ exports.FILE_DOWNLOAD = "file.download"; // ProjectManager.js + + /** Downloads the entire project */ exports.FILE_DOWNLOAD_PROJECT = "file.downloadProject"; // ProjectManager.js + + /** Cuts the selected file or folder to clipboard */ exports.FILE_CUT = "file.cut"; // ProjectManager.js + + /** Copies the selected file or folder to clipboard */ exports.FILE_COPY = "file.copy"; // ProjectManager.js + + /** Copies the path of selected file or folder */ exports.FILE_COPY_PATH = "file.copy.path"; // ProjectManager.js + + /** Pastes file or folder from clipboard */ exports.FILE_PASTE = "file.paste"; // ProjectManager.js + + /** Opens a file */ exports.FILE_OPEN = "file.open"; // DocumentCommandHandlers.js handleDocumentOpen() + + /** Opens a folder as a project */ exports.FILE_OPEN_FOLDER = "file.openFolder"; // ProjectManager.js openProject() + + /** Saves the current file */ exports.FILE_SAVE = "file.save"; // DocumentCommandHandlers.js handleFileSave() + + /** Saves all open files */ exports.FILE_SAVE_ALL = "file.saveAll"; // DocumentCommandHandlers.js handleFileSaveAll() + + /** Saves current file with a new name */ exports.FILE_SAVE_AS = "file.saveAs"; // DocumentCommandHandlers.js handleFileSaveAs() + + /** Closes the current file */ exports.FILE_CLOSE = "file.close"; // DocumentCommandHandlers.js handleFileClose() + + /** Closes all open files */ exports.FILE_CLOSE_ALL = "file.close_all"; // DocumentCommandHandlers.js handleFileCloseAll() + + /** Closes files from list */ exports.FILE_CLOSE_LIST = "file.close_list"; // DocumentCommandHandlers.js handleFileCloseList() + + /** Reopens last closed file */ exports.FILE_REOPEN_CLOSED = "file.reopen_closed"; // DocumentCommandHandlers.js handleReopenClosed() + + /** Opens files that were dropped */ exports.FILE_OPEN_DROPPED_FILES = "file.openDroppedFiles"; // DragAndDrop.js openDroppedFiles() + + /** Toggles live file preview */ exports.FILE_LIVE_FILE_PREVIEW = "file.liveFilePreview"; // LiveDevelopment/main.js _handleGoLiveCommand() + + /** Opens live preview settings */ exports.FILE_LIVE_FILE_PREVIEW_SETTINGS = "file.liveFilePreviewSettings"; // LiveDevelopment/main.js _handleGoLiveCommand() + + /** Toggles live preview multi-browser mode */ exports.TOGGLE_LIVE_PREVIEW_MB_MODE = "file.toggleLivePreviewMB"; // LiveDevelopment/main.js _toggleLivePreviewMultiBrowser() + + /** Reloads live preview */ exports.CMD_RELOAD_LIVE_PREVIEW = "file.reloadLivePreview"; // LiveDevelopment/main.js _handleReloadLivePreviewCommand() + + /** Toggles live highlight */ exports.FILE_LIVE_HIGHLIGHT = "file.previewHighlight"; // LiveDevelopment/main.js _handlePreviewHighlightCommand() + + /** Opens project settings */ exports.FILE_PROJECT_SETTINGS = "file.projectSettings"; // ProjectManager.js _projectSettings() + + /** Renames selected file or folder */ exports.FILE_RENAME = "file.rename"; // DocumentCommandHandlers.js handleFileRename() + + /** Deletes selected file or folder */ exports.FILE_DELETE = "file.delete"; // DocumentCommandHandlers.js handleFileDelete() + + /** Opens extension manager */ exports.FILE_EXTENSION_MANAGER = "file.extensionManager"; // ExtensionManagerDialog.js _showDialog() + + /** Refreshes the file tree */ exports.FILE_REFRESH = "file.refresh"; // ProjectManager.js refreshFileTree() + + /** Toggles show folders first in file tree */ exports.FILE_SHOW_FOLDERS_FIRST = "file.showFolderFirst"; // ProjectManager.js + + /** Opens preferences */ exports.FILE_OPEN_PREFERENCES = "file.openPreferences"; // PreferencesManager.js _handleOpenPreferences() + + /** Opens keymap settings */ exports.FILE_OPEN_KEYMAP = "file.openKeyMap"; // KeyBindingManager.js _openUserKeyMap() - // File shell callbacks - string must MATCH string in native code (appshell/command_callbacks.h) + /** Opens new window */ exports.FILE_NEW_WINDOW = "file.new_window"; // DocumentCommandHandlers.js handleFileNewWindow() + + /** Closes current window */ exports.FILE_CLOSE_WINDOW = "file.close_window"; // DocumentCommandHandlers.js handleFileCloseWindow() + + /** Quits the application */ exports.FILE_QUIT = "file.quit"; // DocumentCommandHandlers.js handleFileQuit() + + // EDIT // File shell callbacks - string must MATCH string in native code (appshell/command_callbacks.h) + /** Undoes the last edit operation */ exports.EDIT_UNDO = "edit.undo"; // EditorCommandHandlers.js handleUndo() + + /** Redoes the last undone edit operation */ exports.EDIT_REDO = "edit.redo"; // EditorCommandHandlers.js handleRedo() + + /** Cuts the selected text to clipboard */ exports.EDIT_CUT = "edit.cut"; // EditorCommandHandlers.js ignoreCommand() + + /** Copies the selected text to clipboard */ exports.EDIT_COPY = "edit.copy"; // EditorCommandHandlers.js ignoreCommand() + + /** Pastes text from clipboard */ exports.EDIT_PASTE = "edit.paste"; // EditorCommandHandlers.js ignoreCommand() + + /** Selects all text in the current document */ exports.EDIT_SELECT_ALL = "edit.selectAll"; // EditorCommandHandlers.js _handleSelectAll() + /** Selects the current line */ exports.EDIT_SELECT_LINE = "edit.selectLine"; // EditorCommandHandlers.js selectLine() + + /** Splits selection into individual lines */ exports.EDIT_SPLIT_SEL_INTO_LINES = "edit.splitSelIntoLines"; // EditorCommandHandlers.js splitSelIntoLines() + + /** Adds cursor to the next line */ exports.EDIT_ADD_CUR_TO_NEXT_LINE = "edit.addCursorToNextLine"; // EditorCommandHandlers.js addCursorToNextLine() + + /** Adds cursor to the previous line */ exports.EDIT_ADD_CUR_TO_PREV_LINE = "edit.addCursorToPrevLine"; // EditorCommandHandlers.js addCursorToPrevLine() + + /** Indents the selected text */ exports.EDIT_INDENT = "edit.indent"; // EditorCommandHandlers.js indentText() + + /** Unindents the selected text */ exports.EDIT_UNINDENT = "edit.unindent"; // EditorCommandHandlers.js unindentText() + + /** Duplicates the selected text */ exports.EDIT_DUPLICATE = "edit.duplicate"; // EditorCommandHandlers.js duplicateText() + + /** Deletes the current line(s) */ exports.EDIT_DELETE_LINES = "edit.deletelines"; // EditorCommandHandlers.js deleteCurrentLines() + + /** Toggles line comment for current selection */ exports.EDIT_LINE_COMMENT = "edit.lineComment"; // EditorCommandHandlers.js lineComment() + + /** Toggles block comment for current selection */ exports.EDIT_BLOCK_COMMENT = "edit.blockComment"; // EditorCommandHandlers.js blockComment() + + /** Moves current line up */ exports.EDIT_LINE_UP = "edit.lineUp"; // EditorCommandHandlers.js moveLineUp() + + /** Moves current line down */ exports.EDIT_LINE_DOWN = "edit.lineDown"; // EditorCommandHandlers.js moveLineDown() + + /** Opens a new line above current line */ exports.EDIT_OPEN_LINE_ABOVE = "edit.openLineAbove"; // EditorCommandHandlers.js openLineAbove() + + /** Opens a new line below current line */ exports.EDIT_OPEN_LINE_BELOW = "edit.openLineBelow"; // EditorCommandHandlers.js openLineBelow() + + /** Toggles auto close brackets */ exports.TOGGLE_CLOSE_BRACKETS = "edit.autoCloseBrackets"; // EditorOptionHandlers.js _getToggler() + + /** Shows code hints */ exports.SHOW_CODE_HINTS = "edit.showCodeHints"; // CodeHintManager.js _startNewSession() + + /** Beautifies the current code */ exports.EDIT_BEAUTIFY_CODE = "edit.beautifyCode"; // CodeHintManager.js _startNewSession() + + /** Toggles code beautification on save */ exports.EDIT_BEAUTIFY_CODE_ON_SAVE = "edit.beautifyOnSave"; // CodeHintManager.js _startNewSession() - // FIND + /** Opens find dialog */ exports.CMD_FIND = "cmd.find"; // FindReplace.js _launchFind() + + /** Opens find in files dialog */ exports.CMD_FIND_IN_FILES = "cmd.findInFiles"; // FindInFilesUI.js _showFindBar() + + /** Opens find in subtree dialog */ exports.CMD_FIND_IN_SUBTREE = "cmd.findInSubtree"; // FindInFilesUI.js _showFindBarForSubtree() + + /** Finds next match */ exports.CMD_FIND_NEXT = "cmd.findNext"; // FindReplace.js _findNext() + + /** Finds previous match */ exports.CMD_FIND_PREVIOUS = "cmd.findPrevious"; // FindReplace.js _findPrevious() + + /** Finds all matches and selects them */ exports.CMD_FIND_ALL_AND_SELECT = "cmd.findAllAndSelect"; // FindReplace.js _findAllAndSelect() + + /** Adds next match to selection */ exports.CMD_ADD_NEXT_MATCH = "cmd.addNextMatch"; // FindReplace.js _expandAndAddNextToSelection() + + /** Skips current match */ exports.CMD_SKIP_CURRENT_MATCH = "cmd.skipCurrentMatch"; // FindReplace.js _skipCurrentMatch() + + /** Replaces current match */ exports.CMD_REPLACE = "cmd.replace"; // FindReplace.js _replace() + + /** Opens replace in files dialog */ exports.CMD_REPLACE_IN_FILES = "cmd.replaceInFiles"; // FindInFilesUI.js _showReplaceBar() + + /** Opens replace in subtree dialog */ exports.CMD_REPLACE_IN_SUBTREE = "cmd.replaceInSubtree"; // FindInFilesUI.js _showReplaceBarForSubtree() + + /** Opens find references panel */ exports.CMD_FIND_ALL_REFERENCES = "cmd.findAllReferences"; // findReferencesManager.js _openReferencesPanel() // VIEW + /** Opens theme settings */ exports.CMD_THEMES_OPEN_SETTINGS = "view.themesOpenSetting"; // MenuCommands.js Settings.open() + + /** Toggles sidebar visibility */ exports.VIEW_HIDE_SIDEBAR = "view.toggleSidebar"; // SidebarView.js toggle() + + /** Zooms in the editor view */ exports.VIEW_ZOOM_IN = "view.zoomIn"; // ViewCommandHandlers.js _handleZoomIn() + + /** Zooms out the editor view */ exports.VIEW_ZOOM_OUT = "view.zoomOut"; // ViewCommandHandlers.js _handleZoomOut() + + /** Submenu for zoom options */ exports.VIEW_ZOOM_SUBMENU = "zoom-view-submenu"; + + /** Increases editor font size */ exports.VIEW_INCREASE_FONT_SIZE = "view.increaseFontSize"; // ViewCommandHandlers.js _handleIncreaseFontSize() + + /** Decreases editor font size */ exports.VIEW_DECREASE_FONT_SIZE = "view.decreaseFontSize"; // ViewCommandHandlers.js _handleDecreaseFontSize() + + /** Restores editor font size to default */ exports.VIEW_RESTORE_FONT_SIZE = "view.restoreFontSize"; // ViewCommandHandlers.js _handleRestoreFontSize() + + /** Scrolls editor view up by one line */ exports.VIEW_SCROLL_LINE_UP = "view.scrollLineUp"; // ViewCommandHandlers.js _handleScrollLineUp() + + /** Scrolls editor view down by one line */ exports.VIEW_SCROLL_LINE_DOWN = "view.scrollLineDown"; // ViewCommandHandlers.js _handleScrollLineDown() + + /** Toggles code inspection */ exports.VIEW_TOGGLE_INSPECTION = "view.toggleCodeInspection"; // CodeInspection.js toggleEnabled() + + /** Toggles problems panel visibility */ exports.VIEW_TOGGLE_PROBLEMS = "view.toggleProblems"; // CodeInspection.js toggleProblems() + + /** Toggles line numbers visibility */ exports.TOGGLE_LINE_NUMBERS = "view.toggleLineNumbers"; // EditorOptionHandlers.js _getToggler() + + /** Toggles active line highlight */ exports.TOGGLE_ACTIVE_LINE = "view.toggleActiveLine"; // EditorOptionHandlers.js _getToggler() + + /** Toggles word wrap */ exports.TOGGLE_WORD_WRAP = "view.toggleWordWrap"; // EditorOptionHandlers.js _getToggler() + + /** Toggles rulers visibility */ exports.TOGGLE_RULERS = "view.toggleRulers"; // EditorOptionHandlers.js + + /** Toggles indent guides visibility */ exports.TOGGLE_INDENT_GUIDES = "view.toggleIndentGuides"; // integrated extension indentGuides + + /** Toggles search auto-hide behavior */ exports.TOGGLE_SEARCH_AUTOHIDE = "view.toggleSearchAutoHide"; // EditorOptionHandlers.js _getToggler() + /** Opens a file */ exports.CMD_OPEN = "cmd.open"; + + /** Adds file to working set and opens it */ exports.CMD_ADD_TO_WORKINGSET_AND_OPEN = "cmd.addToWorkingSetAndOpen"; // DocumentCommandHandlers.js handleOpenDocumentInNewPane() + // ADD_TO_WORKING_SET is deprectated but we need a handler for it because the new command doesn't return the same result as the legacy command exports.FILE_ADD_TO_WORKING_SET = "file.addToWorkingSet"; // Deprecated through DocumentCommandHandlers.js handleFileAddToWorkingSet // NAVIGATE + /** Goes to next document */ exports.NAVIGATE_NEXT_DOC = "navigate.nextDoc"; // DocumentCommandHandlers.js handleGoNextDoc() + + /** Goes to previous document */ exports.NAVIGATE_PREV_DOC = "navigate.prevDoc"; // DocumentCommandHandlers.js handleGoPrevDoc() + + /** Goes to next document in list order */ exports.NAVIGATE_NEXT_DOC_LIST_ORDER = "navigate.nextDocListOrder"; // DocumentCommandHandlers.js handleGoNextDocListOrder() + + /** Goes to previous document in list order */ exports.NAVIGATE_PREV_DOC_LIST_ORDER = "navigate.prevDocListOrder"; // DocumentCommandHandlers.js handleGoPrevDocListOrder() + + /** Shows current file in file tree */ exports.NAVIGATE_SHOW_IN_FILE_TREE = "navigate.showInFileTree"; // DocumentCommandHandlers.js handleShowInTree() + + /** Shows current file in OS file explorer */ exports.NAVIGATE_SHOW_IN_OS = "navigate.showInOS"; // DocumentCommandHandlers.js handleShowInOS() + + /** Opens quick open dialog */ exports.NAVIGATE_QUICK_OPEN = "navigate.quickOpen"; // QuickOpen.js doFileSearch() + + /** Jumps to definition of symbol at cursor */ exports.NAVIGATE_JUMPTO_DEFINITION = "navigate.jumptoDefinition"; // JumpToDefManager.js _doJumpToDef() + + /** Opens go to definition search */ exports.NAVIGATE_GOTO_DEFINITION = "navigate.gotoDefinition"; // QuickOpen.js doDefinitionSearch() + + /** Opens go to definition in project search */ exports.NAVIGATE_GOTO_DEFINITION_PROJECT = "navigate.gotoDefinitionInProject"; // QuickOpen.js doDefinitionSearchInProject() + + /** Opens go to line dialog */ exports.NAVIGATE_GOTO_LINE = "navigate.gotoLine"; // QuickOpen.js doGotoLine() + + /** Goes to first problem in current file */ exports.NAVIGATE_GOTO_FIRST_PROBLEM = "navigate.gotoFirstProblem"; // CodeInspection.js handleGotoFirstProblem() + + /** Goes to next problem in current file */ exports.NAVIGATE_GOTO_NEXT_PROBLEM = "navigate.gotoNextProblem"; // CodeInspection.js handleGotoNextProblem() + + /** Goes to previous problem in current file */ exports.NAVIGATE_GOTO_PREV_PROBLEM = "navigate.gotoPrevProblem"; // CodeInspection.js handleGotoPrevProblem() + + /** Toggles quick edit widget */ exports.TOGGLE_QUICK_EDIT = "navigate.toggleQuickEdit"; // EditorManager.js _toggleInlineWidget() + + /** Toggles quick docs widget */ exports.TOGGLE_QUICK_DOCS = "navigate.toggleQuickDocs"; // EditorManager.js _toggleInlineWidget() + + /** Goes to next match in quick edit */ exports.QUICK_EDIT_NEXT_MATCH = "navigate.nextMatch"; // MultiRangeInlineEditor.js _nextRange() + + /** Goes to previous match in quick edit */ exports.QUICK_EDIT_PREV_MATCH = "navigate.previousMatch"; // MultiRangeInlineEditor.js _previousRange() + + /** Creates new CSS rule in quick edit */ exports.CSS_QUICK_EDIT_NEW_RULE = "navigate.newRule"; // CSSInlineEditor.js _handleNewRule() + // HELP + /** Opens how to use Brackets guide */ exports.HELP_HOW_TO_USE_BRACKETS = "help.howToUseBrackets"; // HelpCommandHandlers.js _handleLinkMenuItem() + + /** Opens documentation */ exports.HELP_DOCS = "help.docs"; // HelpCommandHandlers.js _handleLinkMenuItem() + + /** Opens support resources */ exports.HELP_SUPPORT = "help.support"; // HelpCommandHandlers.js _handleLinkMenuItem() + + /** Opens feature suggestion page */ exports.HELP_SUGGEST = "help.suggest"; // HelpCommandHandlers.js _handleLinkMenuItem() + + /** Opens release notes */ exports.HELP_RELEASE_NOTES = "help.releaseNotes"; // HelpCommandHandlers.js _handleLinkMenuItem() + + /** Opens contributor guidelines */ exports.HELP_GET_INVOLVED = "help.getInvolved"; // HelpCommandHandlers.js _handleLinkMenuItem() + + /** Shows extensions folder in OS */ exports.HELP_SHOW_EXT_FOLDER = "help.showExtensionsFolder"; // HelpCommandHandlers.js _handleShowExtensionsFolder() + + /** Opens project homepage */ exports.HELP_HOMEPAGE = "help.homepage"; // HelpCommandHandlers.js _handleLinkMenuItem() + + /** Opens YouTube channel */ exports.HELP_YOUTUBE = "help.youtube"; // HelpCommandHandlers.js _handleLinkMenuItem() + + /** Opens Twitter page */ exports.HELP_TWITTER = "help.twitter"; // HelpCommandHandlers.js _handleLinkMenuItem() + + /** Toggles keyboard shortcuts panel */ exports.HELP_TOGGLE_SHORTCUTS_PANEL = "help.toggleShortcuts"; // shortcuts integrated extension + + /** Checks for updates */ exports.HELP_CHECK_UPDATES = "help.checkUpdates"; // shortcuts integrated extension + + /** Toggles auto update */ exports.HELP_AUTO_UPDATE = "help.autoUpdate"; // shortcuts integrated extension // Working Set Configuration + /** Sorts working set by order files were added */ exports.CMD_WORKINGSET_SORT_BY_ADDED = "cmd.sortWorkingSetByAdded"; // WorkingSetSort.js _handleSort() + + /** Sorts working set by file name */ exports.CMD_WORKINGSET_SORT_BY_NAME = "cmd.sortWorkingSetByName"; // WorkingSetSort.js _handleSort() + + /** Sorts working set by file type */ exports.CMD_WORKINGSET_SORT_BY_TYPE = "cmd.sortWorkingSetByType"; // WorkingSetSort.js _handleSort() + + /** Toggles automatic working set sorting */ exports.CMD_WORKING_SORT_TOGGLE_AUTO = "cmd.sortWorkingSetToggleAuto"; // WorkingSetSort.js _handleToggleAutoSort() + + /** Opens keyboard navigation UI overlay */ exports.CMD_KEYBOARD_NAV_UI_OVERLAY = "cmd.keyboardNavUI"; // WorkingSetSort.js _handleToggleAutoSort() // Split View + /** Removes split view */ exports.CMD_SPLITVIEW_NONE = "cmd.splitViewNone"; // SidebarView.js _handleSplitNone() + + /** Splits view vertically */ exports.CMD_SPLITVIEW_VERTICAL = "cmd.splitViewVertical"; // SidebarView.js _handleSplitVertical() + + /** Splits view horizontally */ exports.CMD_SPLITVIEW_HORIZONTAL = "cmd.splitViewHorizontal"; // SidebarView.js _handleSplitHorizontal() + + /** Switches focus between split panes */ exports.CMD_SWITCH_PANE_FOCUS = "cmd.switchPaneFocus"; // MainViewManager.js _switchPaneFocus() // File shell callbacks - string must MATCH string in native code (appshell/command_callbacks.h) + /** Shows about dialog */ exports.HELP_ABOUT = "help.about"; // HelpCommandHandlers.js _handleAboutDialog() // APP + /** Reloads the application */ exports.APP_RELOAD = "app.reload"; // DocumentCommandHandlers.js handleReload() + + /** Reloads the application without extensions */ exports.APP_RELOAD_WITHOUT_EXTS = "app.reload_without_exts"; // DocumentCommandHandlers.js handleReloadWithoutExts() // File shell callbacks - string must MATCH string in native code (appshell/command_callbacks.h) + /** Aborts application quit */ exports.APP_ABORT_QUIT = "app.abort_quit"; // DocumentCommandHandlers.js handleAbortQuit() + + /** Handler before menu popup */ exports.APP_BEFORE_MENUPOPUP = "app.before_menupopup"; // DocumentCommandHandlers.js handleBeforeMenuPopup() // Show or Hide sidebar + /** Hides the sidebar */ exports.HIDE_SIDEBAR = "view.hideSidebar"; // SidebarView.js hide() + + /** Shows the sidebar */ exports.SHOW_SIDEBAR = "view.showSidebar"; // SidebarView.js show() // DEPRECATED: Working Set Commands diff --git a/src/command/KeyBindingManager.js b/src/command/KeyBindingManager.js index a5aba4cc5d..a68841cf43 100644 --- a/src/command/KeyBindingManager.js +++ b/src/command/KeyBindingManager.js @@ -19,6 +19,8 @@ * */ +// @INCLUDE_IN_API_DOCS + /*globals path, logger*/ /*jslint regexp: true */ /*unittests: KeyBindingManager */ @@ -56,17 +58,50 @@ define(function (require, exports, module) { let KEYMAP_FILENAME = "keymap.json", _userKeyMapFilePath = path.normalize(brackets.app.getApplicationSupportDirectory() + "/" + KEYMAP_FILENAME); - const EVENT_KEY_BINDING_ADDED = "keyBindingAdded", - EVENT_KEY_BINDING_REMOVED = "keyBindingRemoved", - EVENT_NEW_PRESET = "newPreset", - EVENT_PRESET_CHANGED = "presetChanged"; + /** + * key binding add event + * + * @const + * @type {string} + */ + const EVENT_KEY_BINDING_ADDED = "keyBindingAdded"; + /** + * key binding remove event + * + * @const + * @type {string} + */ + const EVENT_KEY_BINDING_REMOVED = "keyBindingRemoved"; + + /** + * new preset event + * + * @const + * @type {string} + */ + const EVENT_NEW_PRESET = "newPreset"; + + /** + * preset change event + * + * @const + * @type {string} + */ + const EVENT_PRESET_CHANGED = "presetChanged"; + + /** + * @const + * @type {Object} + */ const KEY = Keys.KEY; + const knownBindableCommands = new Set(); /** - * @private * Forward declaration for JSLint. + * + * @private * @type {Function} */ let _loadUserKeyMap = _.debounce(_loadUserKeyMapImmediate, 200); @@ -78,8 +113,9 @@ define(function (require, exports, module) { const PREF_TRIPLE_CTRL_KEY_PRESS_ENABLED = "tripleCtrlPalette"; /** - * @private * Maps normalized shortcut descriptor to key binding info. + * + * @private * @type {!Object.} */ let _keyMap = {}, // For the actual key bindings including user specified ones @@ -92,8 +128,9 @@ define(function (require, exports, module) { */ /** - * @private * Maps shortcut descriptor to a command id. + * + * @private * @type {UserKeyBinding} */ let _originalUserKeyMap = {}, @@ -101,23 +138,26 @@ define(function (require, exports, module) { _customKeyMapCache = {}; /** - * @private * Maps commandID to the list of shortcuts that are bound to it. + * + * @private * @type {!Object.>} */ let _commandMap = {}; /** - * @private * An array of command ID for all the available commands including the commands * of installed extensions. + * + * @private * @type {Array.} */ let _allCommands = []; /** + * Maps key names to the corresponding unicode symbols + * * @private - * Maps key names to the corresponding unicode symols * @type {{key: string, displayKey: string}} */ let _displayKeyMap = { "up": "\u2191", @@ -134,33 +174,36 @@ define(function (require, exports, module) { "PageUp", "PageDown", "Home", "End", "Insert", "Delete"]; /** - * @private * Flag to show key binding errors in the key map file. Default is true and * it will be set to false when reloading without extensions. This flag is not * used to suppress errors in loading or parsing the key map file. So if the key * map file is corrupt, then the error dialog still shows up. * + * @private * @type {boolean} */ let _showErrors = true; /** - * @private * Allow clients to toggle key binding + * + * @private * @type {boolean} */ let _enabled = true; /** - * @private * Stack of registered global keydown hooks. + * + * @private * @type {Array.} */ let _globalKeydownHooks = []; /** - * @private * States of Ctrl key down detection + * + * @private * @enum {number} */ let CtrlDownStates = { @@ -170,52 +213,56 @@ define(function (require, exports, module) { }; /** - * @private * Flags used to determine whether right Alt key is pressed. When it is pressed, * the following two keydown events are triggered in that specific order. * * 1. _ctrlDown - flag used to record { ctrlKey: true, keyIdentifier: "Control", ... } keydown event * 2. _altGrDown - flag used to record { ctrlKey: true, altKey: true, keyIdentifier: "Alt", ... } keydown event * + * @private * @type {CtrlDownStates|boolean} */ let _ctrlDown = CtrlDownStates.NOT_YET_DETECTED, _altGrDown = false; /** - * @private * Used to record the timeStamp property of the last keydown event. + * + * @private * @type {number} */ let _lastTimeStamp; /** - * @private * Used to record the keyIdentifier property of the last keydown event. + * + * @private * @type {string} */ let _lastKeyIdentifier; - /* - * @private + /** * Constant used for checking the interval between Control keydown event and Alt keydown event. * If the right Alt key is down we get Control keydown followed by Alt keydown within 30 ms. if * the user is pressing Control key and then Alt key, the interval will be larger than 30 ms. + * + * @private * @type {number} */ let MAX_INTERVAL_FOR_CTRL_ALT_KEYS = 30; /** - * @private * Forward declaration for JSLint. + * + * @private * @type {Function} */ let _onCtrlUp; /** - * @private * Resets all the flags and removes _onCtrlUp event listener. * + * @private */ function _quitAltGrMode() { _enabled = true; @@ -227,11 +274,11 @@ define(function (require, exports, module) { } /** - * @private * Detects the release of AltGr key by checking all keyup events * until we receive one with ctrl key code. Once detected, reset * all the flags and also remove this event listener. * + * @private * @param {!KeyboardEvent} e keyboard event object */ _onCtrlUp = function (e) { @@ -242,7 +289,6 @@ define(function (require, exports, module) { }; /** - * @private * Detects whether AltGr key is pressed. When it is pressed, the first keydown event has * ctrlKey === true with keyIdentifier === "Control". The next keydown event with * altKey === true, ctrlKey === true and keyIdentifier === "Alt" is sent within 30 ms. Then @@ -257,6 +303,7 @@ define(function (require, exports, module) { * When we detect the addition of Ctrl key besides AltGr key, we also quit AltGr mode and re-enable * KeyBindingManager. * + * @private * @param {!KeyboardEvent} e keyboard event object */ function _detectAltGrKeyDown(e) { @@ -309,9 +356,10 @@ define(function (require, exports, module) { } /** - * @private * Initialize an empty keymap as the current keymap. It overwrites the current keymap if there is one. * builds the keyDescriptor string from the given parts + * + * @private * @param {boolean} hasCtrl Is Ctrl key enabled * @param {boolean} hasAlt Is Alt key enabled * @param {boolean} hasShift Is Shift key enabled @@ -353,7 +401,9 @@ define(function (require, exports, module) { /** * normalizes the incoming key descriptor so the modifier keys are always specified in the correct order - * @param {string} The string for a key descriptor, can be in any order, the result will be Ctrl-Alt-Shift- + * + * @private + * @param {string} origDescriptor The string for a key descriptor, can be in any order, the result will be Ctrl-Alt-Shift- * @return {string} The normalized key descriptor or null if the descriptor invalid */ function normalizeKeyDescriptorString(origDescriptor) { @@ -498,8 +548,9 @@ define(function (require, exports, module) { } /** - * @private * Looks for keycodes that have os-inconsistent keys and fixes them. + * + * @private * @return {string} If the key is OS-inconsistent, the correct key; otherwise, the original key. **/ function _mapKeycodeToKey(event) { @@ -529,6 +580,8 @@ define(function (require, exports, module) { /** * Takes a keyboard event and translates it into a key in a key map + * + * @private */ function _translateKeyboardEvent(event) { let hasMacCtrl = (brackets.platform === "mac") ? (event.ctrlKey) : false, @@ -541,6 +594,7 @@ define(function (require, exports, module) { /** * Convert normalized key representation to display appropriate for platform. + * * @param {!string} descriptor Normalized key descriptor. * @return {!string} Display/Operating system appropriate string */ @@ -623,13 +677,12 @@ define(function (require, exports, module) { } /** - * @private - * * Updates _allCommands array and _defaultKeyMap with the new key binding * if it is not yet in the _allCommands array. _allCommands array is initialized * only in extensionsLoaded event. So any new commands or key bindings added after * that will be updated here. * + * @private * @param {{commandID: string, key: string, displayKey:string, explicitPlatform: string}} newBinding */ function _updateCommandAndKeyMaps(newBinding) { @@ -836,8 +889,8 @@ define(function (require, exports, module) { /** * Returns a copy of the current key map. If the optional 'defaults' parameter is true, * then a copy of the default key map is returned. - * @param {boolean=} defaults true if the caller wants a copy of the default key map. - * Otherwise, the current active key map is returned. + * + * @param {boolean=} defaults true if the caller wants a copy of the default key map. Otherwise, the current active key map is returned. * @return {!Object.} */ function getKeymap(defaults) { @@ -854,7 +907,9 @@ define(function (require, exports, module) { /** * If there is a registered and enabled key event, we always mark the event as processed * except the ones in UN_SWALLOWED_EVENTS. - * @type {(string)[]} + * + * @private + * @type {Array.} */ const UN_SWALLOWED_EVENTS = _makeMapFromArray({}, [ Commands.EDIT_SELECT_ALL, @@ -877,7 +932,8 @@ define(function (require, exports, module) { /** * Process the keybinding for the current key. * - * @param {string} A key-description string. + * @private + * @param {string} key A key-description string. * @return {boolean} true if the key was processed, false otherwise */ function _handleKey(key) { @@ -910,10 +966,10 @@ define(function (require, exports, module) { } /** - * @private - * * Sort objects by platform property. Objects with a platform property come * before objects without a platform property. + * + * @private */ function _sortByPlatform(a, b) { let a1 = (a.platform) ? 1 : 0, @@ -1029,6 +1085,8 @@ define(function (require, exports, module) { const _handledCommands = {}; /** * Adds default key bindings when commands are registered to CommandManager + * + * @private * @param {$.Event} event jQuery event * @param {Command} command Newly registered command */ @@ -1185,6 +1243,8 @@ define(function (require, exports, module) { /** * Handles a given keydown event, checking global hooks first before * deciding to handle it ourselves. + * + * @private * @param {Event} event The keydown event to handle. */ function _handleKeyEvent(event) { @@ -1233,10 +1293,10 @@ define(function (require, exports, module) { }); /** - * @private * Displays an error dialog and also opens the user key map file for editing only if * the error is not the loading file error. * + * @private * @param {?string} err Error type returned from JSON parser or open file operation * @param {string=} message Error message to be displayed in the dialog */ @@ -1265,10 +1325,10 @@ define(function (require, exports, module) { } /** - * @private - * * Checks whether the given command ID is a special command that the user can't bind * to another shortcut. + * + * @private * @param {!string} commandID A string referring to a specific command * @return {boolean} true if normalizedKey is a special command, false otherwise. */ @@ -1281,10 +1341,10 @@ define(function (require, exports, module) { } /** - * @private - * * Checks whether the given key combination is a shortcut of a special command * or a Mac system command that the user can't reassign to another command. + * + * @private * @param {!string} normalizedKey A key combination string used for a keyboard shortcut * @return {boolean} true if normalizedKey is a restricted shortcut, false otherwise. */ @@ -1306,9 +1366,9 @@ define(function (require, exports, module) { } /** - * @private - * * Creates a bullet list item for any item in the given list. + * + * @private * @param {Array.} list An array of strings to be converted into a * message string with a bullet list. * @return {string} the html text version of the list @@ -1323,12 +1383,11 @@ define(function (require, exports, module) { } /** - * @private - * * Gets the corresponding unicode symbol of an arrow key for display in the menu. + * + * @private * @param {string} key The non-modifier key used in the shortcut. It does not need to be normalized. - * @return {string} An empty string if key is not one of those we want to show with the unicode symbol. - * Otherwise, the corresponding unicode symbol is returned. + * @return {string} An empty string if key is not one of those we want to show with the unicode symbol. Otherwise, the corresponding unicode symbol is returned. */ function _getDisplayKey(key) { let displayKey = "", @@ -1340,8 +1399,6 @@ define(function (require, exports, module) { } /** - * @private - * * Applies each user key binding to all the affected commands and updates _keyMap. * Shows errors in a dialog and then opens the user key map file if any of the following * is detected while applying the user key bindings. @@ -1351,6 +1408,8 @@ define(function (require, exports, module) { * - The same key combination is listed for multiple key bindings. * - A key binding has any invalid key syntax. * - A key binding is referring to a non-existent command ID. + * + * @private */ function _applyUserKeyBindings() { let remappedCommands = [], @@ -1469,10 +1528,10 @@ define(function (require, exports, module) { } /** - * @private - * * Restores the default key bindings for all the commands that are modified by each key binding * specified in _customKeyMapCache (old version) but no longer specified in _customKeyMap (new version). + * + * @private */ function _undoPriorUserKeyBindings() { _.forEach(_customKeyMapCache, function (commandID, key) { @@ -1509,12 +1568,11 @@ define(function (require, exports, module) { } /** - * @private - * * Gets the full file path to the user key map file. In testing environment * a different file path is returned so that running integration tests won't * pop up the error dialog showing the errors from the actual user key map file. * + * @private * @return {string} full file path to the user key map file. */ function _getUserKeyMapFilePath() { @@ -1571,13 +1629,12 @@ define(function (require, exports, module) { } /** - * @private - * * Reads in the user key map file and parses its content into JSON. * Returns the user key bindings if JSON has "overrides". * Otherwise, returns an empty object or an error if the file * cannot be parsed or loaded. * + * @private * @return {$.Promise} a jQuery promise that will be resolved with the JSON * object if the user key map file has "overrides" property or an empty JSON. * If the key map file cannot be read or cannot be parsed by the JSON parser, @@ -1621,6 +1678,7 @@ define(function (require, exports, module) { /** * This can be used by extensions to register new kepmap packs that can be listed in the keyboard shortcuts panel * under use preset dropdown. For EG. distribute a `netbeans editor` shortcuts pack via extension. + * * @param {string} packID - A unique ID for the pack. Use `extensionID.name` format to avoid collisions. * @param {string} packName - A name for the pack. * @param {Object} keyMap - a keymap of the format {`Ctrl-Alt-L`: `file.liveFilePreview`} depending on the platform. @@ -1642,6 +1700,12 @@ define(function (require, exports, module) { exports.trigger(EVENT_NEW_PRESET, packID); } + /** + * Responsible to get all the custom keymap packs + * + * @returns {Array.} an array of all the custom keymap packs, + * each pack is an object with keys: `packID`, `packageName` & `keyMap` + */ function getAllCustomKeymapPacks() { const packDetails = []; for(let packID of Object.keys(_registeredCustomKeyMaps)){ @@ -1654,6 +1718,11 @@ define(function (require, exports, module) { return packDetails; } + /** + * To get the current custom keymap pack + * + * @returns {Object} the current custom keymap pack + */ function getCurrentCustomKeymapPack() { return _registeredCustomKeyMaps[_customKeymapIDInUse]; } @@ -1662,6 +1731,7 @@ define(function (require, exports, module) { * Determines the origin of a custom keyboard shortcut is from user keymap.json or a custom keymap preset. * If it is neither (Eg. phoenix default shortcuts, will return null.) * + * @private * @param {string} shortcut - The keyboard shortcut to check. * @returns {string|null} - The origin of the custom shortcut, or null if it is not a custom shortcut. */ @@ -1679,6 +1749,7 @@ define(function (require, exports, module) { /** * internal use, this is for setting the current custom keyboard pack. + * * @param packID * @private */ @@ -1740,8 +1811,6 @@ define(function (require, exports, module) { } /** - * @private - * * Reads in the user key bindings and updates the key map with each user key * binding by removing the existing one assigned to each key and adding * new one for the specified command id. Shows errors and opens the user @@ -1749,7 +1818,9 @@ define(function (require, exports, module) { * * This function is wrapped with debounce so that its execution is always delayed * by 200 ms. The delay is required because when this function is called some - * extensions may still be adding some commands and their key bindings asychronously. + * extensions may still be adding some commands and their key bindings asynchronously. + * + * @private */ function _loadUserKeyMapImmediate() { return new Promise((resolve, reject)=>{ @@ -1779,6 +1850,7 @@ define(function (require, exports, module) { /** * resets all user defined shortcuts + * * @return {Promise|Promise|*} */ function resetUserShortcutsAsync() { @@ -1798,10 +1870,10 @@ define(function (require, exports, module) { } /** - * @private - * * Opens the existing key map file or creates a new one with default content * if it does not exist. + * + * @private */ function _openUserKeyMap() { let userKeyMapPath = _getUserKeyMapFilePath(), @@ -1831,10 +1903,10 @@ define(function (require, exports, module) { }); /** - * @private - * * Initializes _allCommands array and _defaultKeyMap so that we can use them for * detecting non-existent commands and restoring the original key binding. + * + * @private */ function _initCommandAndKeyMaps() { _allCommands = CommandManager.getAll(); @@ -1844,11 +1916,10 @@ define(function (require, exports, module) { } /** - * @private - * * Sets the full file path to the user key map file. Only used by unit tests * to load a test file instead of the actual user key map file. * + * @private * @param {string} fullPath file path to the user key map file. */ function _setUserKeyMapFilePath(fullPath) { @@ -1877,6 +1948,11 @@ define(function (require, exports, module) { _loadUserKeyMap(); }); + /** + * Whether the keyboard is in overlay mode or not + * + * @returns {boolean} True if in overlay mode else false + */ function isInOverlayMode() { return KeyboardOverlayMode.isInOverlayMode(); } @@ -1942,6 +2018,12 @@ define(function (require, exports, module) { let keyboardShortcutCaptureInProgress = null, keyboardShortcutDialog = null, capturedShortcut = null; + + /** + * to display the shortcut selection dialog + * + * @param command + */ function showShortcutSelectionDialog(command) { Metrics.countEvent(Metrics.EVENT_TYPE.KEYBOARD, 'shortcut', "DialogShown"); if(_isSpecialCommand(command.getID())){ @@ -1988,6 +2070,7 @@ define(function (require, exports, module) { /** * Returns true the given command id can be overriden by user. + * * @param commandId * @return {boolean} */ @@ -1999,6 +2082,7 @@ define(function (require, exports, module) { * gets a list of commands that are known to have had a key binding in this session. Note that this will contain * commands that may not currently have a key binding. IT is mainly used in keyboard shortcuts panel to list items * that can be assigned a key binding. + * * @type {Set} * @private */ diff --git a/src/command/KeyboardOverlayMode.js b/src/command/KeyboardOverlayMode.js index 93ee6a31f1..93921ccb9c 100644 --- a/src/command/KeyboardOverlayMode.js +++ b/src/command/KeyboardOverlayMode.js @@ -19,6 +19,8 @@ * */ +// @INCLUDE_IN_API_DOCS + /*global Phoenix*/ /** @@ -68,6 +70,9 @@ define(function (require, exports, module) { } } + /** + * Responsible to start the overlay mode + */ function startOverlayMode() { overlayOrderCentralElement = calculateUINavOrder(); currentOverlayElement = overlayOrderCentralElement; @@ -110,6 +115,10 @@ define(function (require, exports, module) { return secondPane; } + /** + * Responsible to exit the overlay mode. + * restores focus to previously active pane + */ function exitOverlayMode() { const overlay = document.getElementById(CONTROL_NAV_OVERLAY_ID); overlay.classList.add('forced-hidden'); // Remove the class that hides the overlay @@ -120,6 +129,12 @@ define(function (require, exports, module) { document.removeEventListener('click', exitOverlayMode, true); } + /** + * Handles the keyboard navigation in overlay mode + * Process the arrow keys to move between panes, Enter to select a pane, and Escape to exit overlay mode + * + * @param {KeyboardEvent} event + */ function processOverlayKeyboardEvent(event) { const upElement = currentOverlayElement.up; const downElement = currentOverlayElement.down; @@ -171,6 +186,11 @@ define(function (require, exports, module) { return true; } + /** + * to check whether in overlay mode or not + * + * @returns {boolean} returns true if in overlay mode otherwise false + */ function isInOverlayMode() { return overlayMode; } diff --git a/src/command/Keys.js b/src/command/Keys.js index 6a5f17f12d..223fd643ae 100644 --- a/src/command/Keys.js +++ b/src/command/Keys.js @@ -19,12 +19,20 @@ * */ +// @INCLUDE_IN_API_DOCS + /*global Phoenix*/ /** * Initializes the default brackets menu items. */ define(function (require, exports, module) { + + /** + * Defines common keyboard key identifiers for use in keyboard event handling. + * + * @enum {string} KEY + */ const KEY = { ENTER: "Enter", RETURN: "Return",