From 0af0d129e7125845a4ec62f9fc72f627b1c22988 Mon Sep 17 00:00:00 2001 From: Pluto Date: Mon, 28 Oct 2024 18:07:03 +0530 Subject: [PATCH 1/2] docs: refine API docs for files in Widgets dir --- docs/API-Reference/widgets/DropdownButton.md | 67 ++++++++-------- docs/API-Reference/widgets/ModalBar.md | 54 +++++-------- docs/API-Reference/widgets/NotificationUI.md | 80 ++++++++++++++++++-- docs/API-Reference/widgets/PopUpManager.md | 24 ++---- src/widgets/DropdownButton.js | 39 ++++++++-- src/widgets/ModalBar.js | 4 + src/widgets/NotificationUI.js | 10 +++ src/widgets/PopUpManager.js | 3 +- 8 files changed, 186 insertions(+), 95 deletions(-) diff --git a/docs/API-Reference/widgets/DropdownButton.md b/docs/API-Reference/widgets/DropdownButton.md index accbe5b8f8..cb73a16e97 100644 --- a/docs/API-Reference/widgets/DropdownButton.md +++ b/docs/API-Reference/widgets/DropdownButton.md @@ -3,10 +3,38 @@ const DropdownButton = brackets.getModule("widgets/DropdownButton") ``` + + +## EVENT\_SELECTED : string +Event triggered when an item is selected. + +**Kind**: global constant + + +## EVENT\_LIST\_RENDERED : string +Event triggered when the list is rendered. + +**Kind**: global constant + + +## EVENT\_DROPDOWN\_SHOWN : string +Event triggered when the dropdown is shown. + +**Kind**: global constant + + +## EVENT\_DROPDOWN\_CLOSED : string +Event triggered when the dropdown is closed. + +**Kind**: global constant ## DropdownButton(label, items, [itemRenderer], [options]) -Creates a single dropdown-button instance. The DOM node is created but not attached to the document anywhere - clients should append `this.$button` to the appropriate location. DropdownButton dispatches the following events: - "select" - triggered when an option in the dropdown is clicked. Passed item object and index. +Creates a single dropdown-button instance. The DOM node is created but not attached to +the document anywhere - clients should append `this.$button` to the appropriate location. + +DropdownButton dispatches the following events: + - "select" - triggered when an option in the dropdown is clicked. Passed item object and index. **Kind**: global function @@ -24,13 +52,10 @@ Creates a single dropdown-button instance. The DOM node is created but not attac * [DropdownButton(label, items, [itemRenderer], [options])](#DropdownButton) * [.items](#DropdownButton+items) : Array.<\*> * [.itemsSearchFilterText](#DropdownButton+itemsSearchFilterText) : null - * [.$button](#DropdownButton+$button) : jQueryObject - * [.$dropdown](#DropdownButton+$dropdown) : jQueryObject * [.dropdownExtraClasses](#DropdownButton+dropdownExtraClasses) : string * [.setButtonLabel(label)](#DropdownButton+setButtonLabel) * [.isOpen()](#DropdownButton+isOpen) * [.itemRenderer(item, index)](#DropdownButton+itemRenderer) ⇒ string \| Object - * [._renderList($parent)](#DropdownButton+_renderList) ⇒ jQueryObject * [.refresh()](#DropdownButton+refresh) * [.setChecked(index, checked)](#DropdownButton+setChecked) * [.showDropdown()](#DropdownButton+showDropdown) @@ -47,19 +72,8 @@ Items in dropdown list - may be changed any time dropdown isn't open ### dropdownButton.itemsSearchFilterText : null -This is filter text corresponding to each items. it will be used to filter the items based on the keyboard key presses the user does to enter search filter in popup. - -**Kind**: instance property of [DropdownButton](#DropdownButton) - - -### dropdownButton.$button : jQueryObject -The clickable button. Available as soon as the DropdownButton is constructed. - -**Kind**: instance property of [DropdownButton](#DropdownButton) - - -### dropdownButton.$dropdown : jQueryObject -The dropdown element. Only non-null while open. +This is filter text corresponding to each items. it will be used to filter the items based on +the keyboard key presses the user does to enter search filter in popup. **Kind**: instance property of [DropdownButton](#DropdownButton) @@ -91,29 +105,20 @@ returns true if the dropdown is open Called for each item when rendering the dropdown. **Kind**: instance method of [DropdownButton](#DropdownButton) -**Returns**: string \| Object - Formatted & escaped HTML, either as a simple string or as the 'html' field in an object that also conveys enabled state. Disabled items inherit gray text color and cannot be selected. +**Returns**: string \| Object - Formatted & escaped HTML, either as a simple string + or as the 'html' field in an object that also conveys enabled state. Disabled items inherit gray + text color and cannot be selected. | Param | Type | Description | | --- | --- | --- | | item | \* | from items array | | index | number | in items array | - - -### dropdownButton.\_renderList($parent) ⇒ jQueryObject -Converts the list of item objects into HTML list items in format required by DropdownEventHandler - -**Kind**: instance method of [DropdownButton](#DropdownButton) -**Returns**: jQueryObject - The dropdown element with the rendered list items appended. - -| Param | Type | Description | -| --- | --- | --- | -| $parent | jQueryObject | The dropdown element | - ### dropdownButton.refresh() -Refresh the dropdown list by removing and re-creating all list items. Call this after deleting/adding any item in the dropdown list. +Refresh the dropdown list by removing and re-creating all list items. +Call this after deleting/adding any item in the dropdown list. **Kind**: instance method of [DropdownButton](#DropdownButton) diff --git a/docs/API-Reference/widgets/ModalBar.md b/docs/API-Reference/widgets/ModalBar.md index 284467cbcb..f69cbe6720 100644 --- a/docs/API-Reference/widgets/ModalBar.md +++ b/docs/API-Reference/widgets/ModalBar.md @@ -10,20 +10,24 @@ const ModalBar = brackets.getModule("widgets/ModalBar") * [ModalBar](#ModalBar) * [new ModalBar(template, autoClose, animate)](#new_ModalBar_new) - * [._$root](#ModalBar+_$root) - * [._autoClose](#ModalBar+_autoClose) * [.isLockedOpen](#ModalBar+isLockedOpen) : function * [.height()](#ModalBar+height) ⇒ number * [.prepareClose([restoreScrollPos])](#ModalBar+prepareClose) * [.close([restoreScrollPos], [animate], [_reason])](#ModalBar+close) ⇒ $.Promise - * [._handleKeydown()](#ModalBar+_handleKeydown) - * [._handleFocusChange()](#ModalBar+_handleFocusChange) * [.getRoot()](#ModalBar+getRoot) ⇒ jQueryObject ### new ModalBar(template, autoClose, animate) -Creates a modal bar whose contents are the given template. Dispatches one event: - close - When the bar is closed, either via close() or via autoClose. After this event, the bar may remain visible and in the DOM while its closing animation is playing. However, by the time "close" is fired, the bar has been "popped out" of the layout and the editor scroll position has already been restored. Second argument is the reason for closing (one of ModalBar.CLOSE_*). Third argument is the Promise that close() will be returning. +Creates a modal bar whose contents are the given template. + +Dispatches one event: +- close - When the bar is closed, either via close() or via autoClose. After this event, the + bar may remain visible and in the DOM while its closing animation is playing. However, + by the time "close" is fired, the bar has been "popped out" of the layout and the + editor scroll position has already been restored. + Second argument is the reason for closing (one of ModalBar.CLOSE_*). + Third argument is the Promise that close() will be returning. | Param | Type | Description | @@ -32,22 +36,12 @@ Creates a modal bar whose contents are the given template. Dispatches one event | autoClose | boolean | If true, then close the dialog if the user hits Esc or if the bar loses focus. | | animate | boolean | If true (the default), animate the dialog closed, otherwise close it immediately. | - - -### modalBar.\_$root -A jQuery object containing the root node of the ModalBar. - -**Kind**: instance property of [ModalBar](#ModalBar) - - -### modalBar.\_autoClose -True if this ModalBar is set to autoclose. - -**Kind**: instance property of [ModalBar](#ModalBar) ### modalBar.isLockedOpen : function -Allows client code to block autoClose from closing the ModalBar: if set, this function is called whenever autoClose would normally close the ModalBar. Returning true prevents the close from occurring. Programmatically calling close() will still close the bar, however. +Allows client code to block autoClose from closing the ModalBar: if set, this function is called whenever +autoClose would normally close the ModalBar. Returning true prevents the close from occurring. Programmatically +calling close() will still close the bar, however. **Kind**: instance property of [ModalBar](#ModalBar) @@ -58,7 +52,11 @@ Allows client code to block autoClose from closing the ModalBar: if set, this fu ### modalBar.prepareClose([restoreScrollPos]) -Prepares the ModalBar for closing by popping it out of the main flow and resizing/ rescrolling the Editor to maintain its current apparent code position. Useful if you want to do that as a separate operation from actually animating the ModalBar closed and removing it (for example, if you need to switch full editors in between). If you don't call this explicitly, it will get called at the beginning of `close()`. +Prepares the ModalBar for closing by popping it out of the main flow and resizing/ +rescrolling the Editor to maintain its current apparent code position. Useful if +you want to do that as a separate operation from actually animating the ModalBar +closed and removing it (for example, if you need to switch full editors in between). +If you don't call this explicitly, it will get called at the beginning of `close()`. **Kind**: instance method of [ModalBar](#ModalBar) @@ -69,7 +67,8 @@ Prepares the ModalBar for closing by popping it out of the main flow and resizin ### modalBar.close([restoreScrollPos], [animate], [_reason]) ⇒ $.Promise -Closes the modal bar and returns focus to the active editor. Returns a promise that is resolved when the bar is fully closed and the container is removed from the DOM. +Closes the modal bar and returns focus to the active editor. Returns a promise that is +resolved when the bar is fully closed and the container is removed from the DOM. **Kind**: instance method of [ModalBar](#ModalBar) **Returns**: $.Promise - promise resolved when close is finished @@ -80,18 +79,6 @@ Closes the modal bar and returns focus to the active editor. Returns a promise t | [animate] | boolean | If true (the default), animate the closing of the ModalBar, otherwise close it immediately. | | [_reason] | string | For internal use only. | - - -### modalBar.\_handleKeydown() -If autoClose is set, close the bar when Escape is pressed - -**Kind**: instance method of [ModalBar](#ModalBar) - - -### modalBar.\_handleFocusChange() -If autoClose is set, detects when something other than the modal bar is getting focus and dismisses the modal bar. DOM nodes with "attached-to" jQuery metadata referencing an element within the ModalBar are allowed to take focus without closing it. - -**Kind**: instance method of [ModalBar](#ModalBar) ### modalBar.getRoot() ⇒ jQueryObject @@ -100,6 +87,7 @@ If autoClose is set, detects when something other than the modal bar is getting ## MainViewManager -A "modal bar" component. This is a lightweight replacement for modal dialogs that appears at the top of the editor area for operations like Find and Quick Open. +A "modal bar" component. This is a lightweight replacement for modal dialogs that +appears at the top of the editor area for operations like Find and Quick Open. **Kind**: global variable diff --git a/docs/API-Reference/widgets/NotificationUI.md b/docs/API-Reference/widgets/NotificationUI.md index 447a210b5c..f19eb4f6fe 100644 --- a/docs/API-Reference/widgets/NotificationUI.md +++ b/docs/API-Reference/widgets/NotificationUI.md @@ -6,15 +6,48 @@ const NotificationUI = brackets.getModule("widgets/NotificationUI") ## widgets/NotificationUI -The global NotificationUI can be used to create popup notifications over dom elements or generics app notifications. A global `window.EventManager` object is made available in phoenix that can be called anytime after AppStart. This global can be triggered from anywhere without using require context. ## Usage ### Simple example For Eg. Let's say we have to create a popup notification over the HTML element with ID `showInfileTree`. We can do this with the following +The global NotificationUI can be used to create popup notifications over dom elements or generics app notifications. + +A global `window.EventManager` object is made available in phoenix that can be called anytime after AppStart. +This global can be triggered from anywhere without using require context. + +## Usage +### Simple example +For Eg. Let's say we have to create a popup notification over the HTML element with ID `showInfileTree`. +We can do this with the following **Example** -```js const NotificationUI = brackets.getModule("widgets/NotificationUI"); // or use window.NotificationUI global object has the same effect. let notification = NotificationUI.createFromTemplate("Click me to locate the file in file tree", "showInfileTree",{}); notification.done(()=>{ console.log("notification is closed in ui."); }) ``` ### Advanced example Another advanced example where you can specify html and interactive components in the notification +```js +const NotificationUI = brackets.getModule("widgets/NotificationUI"); +// or use window.NotificationUI global object has the same effect. +let notification = NotificationUI.createFromTemplate("Click me to locate the file in file tree", "showInfileTree",{}); +notification.done(()=>{ + console.log("notification is closed in ui."); +}) +``` +### Advanced example +Another advanced example where you can specify html and interactive components in the notification **Example** -```js // note that you can even provide an HTML Element node with // custom event handlers directly here instead of HTML text. let notification1 = NotificationUI.createFromTemplate( "
Click me to locate the file in file tree
", "showInfileTree",{ allowedPlacements: ['top', 'bottom'], dismissOnClick: false, autoCloseTimeS: 300 // auto close the popup after 5 minutes }); // do stuff notification1.done((closeReason)=>{ console.log("notification is closed in ui reason:", closeReason); }) ``` The `createFromTemplate` API can be configured with numerous options. See API options below. +```js +// note that you can even provide an HTML Element node with +// custom event handlers directly here instead of HTML text. +let notification1 = NotificationUI.createFromTemplate( + "
Click me to locate the file in file tree
", "showInfileTree",{ + allowedPlacements: ['top', 'bottom'], + dismissOnClick: false, + autoCloseTimeS: 300 // auto close the popup after 5 minutes + }); +// do stuff +notification1.done((closeReason)=>{ + console.log("notification is closed in ui reason:", closeReason); +}) +``` +The `createFromTemplate` API can be configured with numerous options. See API options below. * [widgets/NotificationUI](#module_widgets/NotificationUI) * [.API](#module_widgets/NotificationUI..API) + * [.NOTIFICATION_STYLES_CSS_CLASS](#module_widgets/NotificationUI..NOTIFICATION_STYLES_CSS_CLASS) : object + * [.CLOSE_REASON](#module_widgets/NotificationUI..CLOSE_REASON) : object * [.createFromTemplate(template, [elementID], [options])](#module_widgets/NotificationUI..createFromTemplate) ⇒ Notification * [.createToastFromTemplate(title, template, [options])](#module_widgets/NotificationUI..createToastFromTemplate) ⇒ Notification @@ -24,10 +57,35 @@ The global NotificationUI can be used to create popup notifications over dom ele This section outlines the properties and methods available in this module **Kind**: inner property of [widgets/NotificationUI](#module_widgets/NotificationUI) + + +### widgets/NotificationUI.NOTIFICATION\_STYLES\_CSS\_CLASS : object +CSS class names for notification styles. + +**Kind**: inner constant of [widgets/NotificationUI](#module_widgets/NotificationUI) + + +### widgets/NotificationUI.CLOSE\_REASON : object +Closing notification reason. + +**Kind**: inner constant of [widgets/NotificationUI](#module_widgets/NotificationUI) ### widgets/NotificationUI.createFromTemplate(template, [elementID], [options]) ⇒ Notification -Creates a new notification popup from given template. The template can either be a string or a jQuery object representing a DOM node that is *not* in the current DOM. Creating a notification popup // note that you can even provide an HTML Element node with // custom event handlers directly here instead of HTML text. let notification1 = NotificationUI.createFromTemplate( ```js "
Click me to locate the file in file tree
", "showInfileTree",{ allowedPlacements: ['top', 'bottom'], dismissOnClick: false, autoCloseTimeS: 300 // auto close the popup after 5 minutes }); ``` +Creates a new notification popup from given template. +The template can either be a string or a jQuery object representing a DOM node that is *not* in the current DOM. + +Creating a notification popup +// note that you can even provide an HTML Element node with +// custom event handlers directly here instead of HTML text. +let notification1 = NotificationUI.createFromTemplate( +```js + "
Click me to locate the file in file tree
", "showInfileTree",{ + allowedPlacements: ['top', 'bottom'], + dismissOnClick: false, + autoCloseTimeS: 300 // auto close the popup after 5 minutes + }); +``` **Kind**: inner method of [widgets/NotificationUI](#module_widgets/NotificationUI) **Returns**: Notification - Object with a done handler that resolves when the notification closes. @@ -41,7 +99,19 @@ Creates a new notification popup from given template. The template can either be ### widgets/NotificationUI.createToastFromTemplate(title, template, [options]) ⇒ Notification -Creates a new toast notification popup from given title and html message. The message can either be a string or a jQuery object representing a DOM node that is *not* in the current DOM. Creating a toast notification popup // note that you can even provide an HTML Element node with // custom event handlers directly here instead of HTML text. let notification1 = NotificationUI.createToastFromTemplate( "Title here", ```js "
Click me to locate the file in file tree
", { dismissOnClick: false, autoCloseTimeS: 300 // auto close the popup after 5 minutes }); ``` +Creates a new toast notification popup from given title and html message. +The message can either be a string or a jQuery object representing a DOM node that is *not* in the current DOM. + +Creating a toast notification popup +// note that you can even provide an HTML Element node with +// custom event handlers directly here instead of HTML text. +let notification1 = NotificationUI.createToastFromTemplate( "Title here", +```js + "
Click me to locate the file in file tree
", { + dismissOnClick: false, + autoCloseTimeS: 300 // auto close the popup after 5 minutes + }); +``` **Kind**: inner method of [widgets/NotificationUI](#module_widgets/NotificationUI) **Returns**: Notification - Object with a done handler that resolves when the notification closes. diff --git a/docs/API-Reference/widgets/PopUpManager.md b/docs/API-Reference/widgets/PopUpManager.md index e4bfa33ed3..5c28bdd673 100644 --- a/docs/API-Reference/widgets/PopUpManager.md +++ b/docs/API-Reference/widgets/PopUpManager.md @@ -27,7 +27,8 @@ Add Esc key handling for a popup DOM element. ## removePopUp($popUp) -Remove Esc key handling for a pop-up. Removes the pop-up from the DOM if the pop-up is currently visible and was not originally attached. +Remove Esc key handling for a pop-up. Removes the pop-up from the DOM +if the pop-up is currently visible and was not originally attached. **Kind**: global function @@ -35,27 +36,12 @@ Remove Esc key handling for a pop-up. Removes the pop-up from the DOM if the pop | --- | --- | | $popUp | jQuery | - - -## removeCurrentPopUp([keyEvent]) -Remove Esc key handling for a pop-up. Removes the pop-up from the DOM if the pop-up is currently visible and was not originally attached. - -**Kind**: global function - -| Param | Type | Description | -| --- | --- | --- | -| [keyEvent] | KeyboardEvent | (optional) | - - - -## \_beforeMenuPopup() -A menu is being popped up, so remove any menu that is currently popped up - -**Kind**: global function ## listenToContextMenu(contextMenu) -Context menus are also created in AppInit.htmlReady(), so they may not yet have been created when we get our AppInit.htmlReady() callback, so we provide this method to tell us when to start listening for their events +Context menus are also created in AppInit.htmlReady(), so they may not +yet have been created when we get our AppInit.htmlReady() callback, so +we provide this method to tell us when to start listening for their events **Kind**: global function diff --git a/src/widgets/DropdownButton.js b/src/widgets/DropdownButton.js index 27f7a2bbd2..b9f53de243 100644 --- a/src/widgets/DropdownButton.js +++ b/src/widgets/DropdownButton.js @@ -48,10 +48,33 @@ define(function (require, exports, module) { ViewUtils = require("utils/ViewUtils"), _ = require("thirdparty/lodash"); - const EVENT_SELECTED = "select", - EVENT_LIST_RENDERED = "listRendered", - EVENT_DROPDOWN_SHOWN = "shown", - EVENT_DROPDOWN_CLOSED = "closed"; + /** + * Event triggered when an item is selected. + * @type {string} + * @const + */ + const EVENT_SELECTED = "select"; + + /** + * Event triggered when the list is rendered. + * @type {string} + * @const + */ + const EVENT_LIST_RENDERED = "listRendered"; + + /** + * Event triggered when the dropdown is shown. + * @type {string} + * @const + */ + const EVENT_DROPDOWN_SHOWN = "shown"; + + /** + * Event triggered when the dropdown is closed. + * @type {string} + * @const + */ + const EVENT_DROPDOWN_CLOSED = "closed"; /** * Creates a single dropdown-button instance. The DOM node is created but not attached to @@ -108,12 +131,14 @@ define(function (require, exports, module) { /** * The clickable button. Available as soon as the DropdownButton is constructed. + * @private * @type {!jQueryObject} */ DropdownButton.prototype.$button = null; /** * The dropdown element. Only non-null while open. + * @private * @type {?jQueryObject} */ DropdownButton.prototype.$dropdown = null; @@ -138,7 +163,6 @@ define(function (require, exports, module) { */ DropdownButton.prototype._dropdownEventHandler = null; - /** * @private * Handle clicking button @@ -186,6 +210,7 @@ define(function (require, exports, module) { /** * Converts the list of item objects into HTML list items in format required by DropdownEventHandler + * @private * @param {!jQueryObject} $parent The dropdown element * @return {!jQueryObject} The dropdown element with the rendered list items appended. */ @@ -307,7 +332,9 @@ define(function (require, exports, module) { }); }; - /** Pops open the dropdown if currently closed. Does nothing if items.length == 0 */ + /** + * Pops open the dropdown if currently closed. Does nothing if items.length == 0 + */ DropdownButton.prototype.showDropdown = function () { // Act like a plain old button if no items to show if (!this.items.length) { diff --git a/src/widgets/ModalBar.js b/src/widgets/ModalBar.js index 27dbbc60a8..e33dcc35f2 100644 --- a/src/widgets/ModalBar.js +++ b/src/widgets/ModalBar.js @@ -104,11 +104,13 @@ define(function (require, exports, module) { /** * A jQuery object containing the root node of the ModalBar. + * @private */ ModalBar.prototype._$root = null; /** * True if this ModalBar is set to autoclose. + * @private */ ModalBar.prototype._autoClose = false; @@ -226,6 +228,7 @@ define(function (require, exports, module) { /** * If autoClose is set, close the bar when Escape is pressed + * @private */ ModalBar.prototype._handleKeydown = function (e) { if (e.keyCode === KeyEvent.DOM_VK_ESCAPE) { @@ -239,6 +242,7 @@ define(function (require, exports, module) { * If autoClose is set, detects when something other than the modal bar is getting focus and * dismisses the modal bar. DOM nodes with "attached-to" jQuery metadata referencing an element * within the ModalBar are allowed to take focus without closing it. + * @private */ ModalBar.prototype._handleFocusChange = function (e) { if (this.isLockedOpen && this.isLockedOpen()) { diff --git a/src/widgets/NotificationUI.js b/src/widgets/NotificationUI.js index 10e9150234..f5f3c03b2f 100644 --- a/src/widgets/NotificationUI.js +++ b/src/widgets/NotificationUI.js @@ -73,6 +73,11 @@ define(function (require, exports, module) { const NOTIFICATION_TYPE_ARROW = "arrow", NOTIFICATION_TYPE_TOAST = "toast"; + /** + * CSS class names for notification styles. + * @type {object} + * @const + */ const NOTIFICATION_STYLES_CSS_CLASS = { INFO: "style-info", WARNING: "style-warning", @@ -81,6 +86,11 @@ define(function (require, exports, module) { DANGER: "style-danger" }; + /** + * Closing notification reason. + * @type {object} + * @const + */ const CLOSE_REASON ={ TIMEOUT: 'closeTimeout', CLICK_DISMISS: 'clickDismiss', diff --git a/src/widgets/PopUpManager.js b/src/widgets/PopUpManager.js index 1357b77888..d90b319dbf 100644 --- a/src/widgets/PopUpManager.js +++ b/src/widgets/PopUpManager.js @@ -90,7 +90,7 @@ define(function (require, exports, module) { /** * Remove Esc key handling for a pop-up. Removes the pop-up from the DOM * if the pop-up is currently visible and was not originally attached. - * + * @private * @param {KeyboardEvent=} keyEvent (optional) */ function removeCurrentPopUp(keyEvent) { @@ -144,6 +144,7 @@ define(function (require, exports, module) { /** * A menu is being popped up, so remove any menu that is currently popped up + * @private */ function _beforeMenuPopup() { removeCurrentPopUp(); From f8fc55f60436778d57dcfab4bc4ab1e2de276a84 Mon Sep 17 00:00:00 2001 From: Pluto Date: Tue, 29 Oct 2024 18:48:47 +0530 Subject: [PATCH 2/2] docs: add new files to API docs and fix mentioned issues --- docs/API-Reference/widgets/DefaultDialogs.md | 56 +++++++ docs/API-Reference/widgets/Dialogs.md | 154 +++++++++++++++++++ docs/API-Reference/widgets/DropdownButton.md | 14 ++ docs/API-Reference/widgets/NotificationUI.md | 30 +++- src/widgets/DefaultDialogs.js | 46 +++++- src/widgets/Dialogs.js | 107 +++++++++++-- src/widgets/DropdownButton.js | 2 - src/widgets/NotificationUI.js | 4 +- 8 files changed, 382 insertions(+), 31 deletions(-) create mode 100644 docs/API-Reference/widgets/DefaultDialogs.md create mode 100644 docs/API-Reference/widgets/Dialogs.md diff --git a/docs/API-Reference/widgets/DefaultDialogs.md b/docs/API-Reference/widgets/DefaultDialogs.md new file mode 100644 index 0000000000..2fae788541 --- /dev/null +++ b/docs/API-Reference/widgets/DefaultDialogs.md @@ -0,0 +1,56 @@ +### Import : +```js +const DefaultDialogs = brackets.getModule("widgets/DefaultDialogs") +``` + + + +## DefaultDialogs +Constants representing dialog IDs +These IDs are used to identify different types of dialogs + + +* [DefaultDialogs](#module_DefaultDialogs) + * [.DIALOG_ID_ERROR](#module_DefaultDialogs.DIALOG_ID_ERROR) : string + * [.DIALOG_ID_INFO](#module_DefaultDialogs.DIALOG_ID_INFO) : string + * [.DIALOG_ID_SAVE_CLOSE](#module_DefaultDialogs.DIALOG_ID_SAVE_CLOSE) : string + * [.DIALOG_ID_EXT_CHANGED](#module_DefaultDialogs.DIALOG_ID_EXT_CHANGED) : string + * [.DIALOG_ID_EXT_DELETED](#module_DefaultDialogs.DIALOG_ID_EXT_DELETED) : string + * [.DIALOG_ID_CHANGE_EXTENSIONS](#module_DefaultDialogs.DIALOG_ID_CHANGE_EXTENSIONS) : string + + + +### DefaultDialogs.DIALOG\_ID\_ERROR : string +ID for error dialog + +**Kind**: static constant of [DefaultDialogs](#module_DefaultDialogs) + + +### DefaultDialogs.DIALOG\_ID\_INFO : string +ID for information dialog (currently uses the same template as DIALOG_ID_ERROR) + +**Kind**: static constant of [DefaultDialogs](#module_DefaultDialogs) + + +### DefaultDialogs.DIALOG\_ID\_SAVE\_CLOSE : string +ID for save and close dialog + +**Kind**: static constant of [DefaultDialogs](#module_DefaultDialogs) + + +### DefaultDialogs.DIALOG\_ID\_EXT\_CHANGED : string +ID for `external change detected` dialog + +**Kind**: static constant of [DefaultDialogs](#module_DefaultDialogs) + + +### DefaultDialogs.DIALOG\_ID\_EXT\_DELETED : string +ID for `external deletion detected` dialog + +**Kind**: static constant of [DefaultDialogs](#module_DefaultDialogs) + + +### DefaultDialogs.DIALOG\_ID\_CHANGE\_EXTENSIONS : string +ID for `change extensions` dialog + +**Kind**: static constant of [DefaultDialogs](#module_DefaultDialogs) diff --git a/docs/API-Reference/widgets/Dialogs.md b/docs/API-Reference/widgets/Dialogs.md new file mode 100644 index 0000000000..d6666941f4 --- /dev/null +++ b/docs/API-Reference/widgets/Dialogs.md @@ -0,0 +1,154 @@ +### Import : +```js +const Dialogs = brackets.getModule("widgets/Dialogs") +``` + + + +## DIALOG\_BTN\_CANCEL : string +`CANCEL` dialog button ID + +**Kind**: global constant + + +## DIALOG\_BTN\_OK : string +`OK` dialog button ID + +**Kind**: global constant + + +## DIALOG\_BTN\_DONTSAVE : string +`DONT SAVE` dialog button ID + +**Kind**: global constant + + +## DIALOG\_BTN\_SAVE\_AS : string +`SAVE AS` dialog button ID + +**Kind**: global constant + + +## DIALOG\_CANCELED : string +`CANCELED` dialog button ID + +**Kind**: global constant + + +## DIALOG\_BTN\_DOWNLOAD : string +`DOWNLOAD` dialog button ID + +**Kind**: global constant + + +## DIALOG\_BTN\_CLASS\_PRIMARY : string +Primary button class name + +**Kind**: global constant + + +## DIALOG\_BTN\_CLASS\_NORMAL : string +Normal button class name + +**Kind**: global constant + + +## DIALOG\_BTN\_CLASS\_LEFT : string +Left-aligned button class name + +**Kind**: global constant + + +## showModalDialogUsingTemplate(template, [autoDismiss]) ⇒ [Dialog](#new_Dialog_new) +Creates a new modal dialog from a given template. +The template can either be a string or a jQuery object representing a DOM node that is *not* in the current DOM. + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| template | string | A string template or jQuery object to use as the dialog HTML. | +| [autoDismiss] | boolean | Whether to automatically dismiss the dialog when one of the buttons is clicked. Default true. If false, you'll need to manually handle button clicks and the Esc key, and dismiss the dialog yourself when ready by calling `close()` on the returned dialog. | + + + +## showModalDialog(dlgClass, [title], [message], [buttons], [autoDismiss]) ⇒ [Dialog](#new_Dialog_new) +Creates a new general purpose modal dialog using the default template and the template variables given +as parameters as described. + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| dlgClass | string | A class name identifier for the dialog. Typically one of DefaultDialogs.* | +| [title] | string | The title of the dialog. Can contain HTML markup. Defaults to "". | +| [message] | string | The message to display in the dialog. Can contain HTML markup. Defaults to "". | +| [buttons] | Array.<{className: string, id: string, text: string, tooltip:string}> | An array of buttons where each button has a class, id tooltip, and text property. The id is used in "data-button-id". Defaults to a single Ok button. Typically className is one of DIALOG_BTN_CLASS_*, id is one of DIALOG_BTN_* | +| [autoDismiss] | boolean | Whether to automatically dismiss the dialog when one of the buttons is clicked. Default true. If false, you'll need to manually handle button clicks and the Esc key, and dismiss the dialog yourself when ready by calling `close()` on the returned dialog. | + + + +## showConfirmDialog(title, message, [autoDismiss]) ⇒ [Dialog](#new_Dialog_new) +Display a confirmation dialog with `OK` and `CANCEL` button + +**Kind**: global function +**Returns**: [Dialog](#new_Dialog_new) - the created dialog instance + +| Param | Type | Description | +| --- | --- | --- | +| title | string | dialog title | +| message | string | message to display in the dialog | +| [autoDismiss] | boolean | whether to automatically dismiss the dialog or not | + + + +## showInfoDialog(title, message, [autoDismiss]) ⇒ [Dialog](#new_Dialog_new) +Display information dialog + +**Kind**: global function +**Returns**: [Dialog](#new_Dialog_new) - the created dialog instance + +| Param | Type | Description | +| --- | --- | --- | +| title | string | dialog title | +| message | string | message to display in the dialog | +| [autoDismiss] | boolean | whether to automatically dismiss the dialog or not | + + + +## showErrorDialog(title, message, [autoDismiss]) ⇒ [Dialog](#new_Dialog_new) +Display error dialog + +**Kind**: global function +**Returns**: [Dialog](#new_Dialog_new) - the created dialog instance + +| Param | Type | Description | +| --- | --- | --- | +| title | string | dialog title | +| message | string | message to display in the dialog | +| [autoDismiss] | boolean | whether to automatically dismiss the dialog or not | + + + +## cancelModalDialogIfOpen(dlgClass, [buttonId]) +Immediately closes any dialog instances with the given class. The dialog callback for each instance will +be called with the special buttonId DIALOG_CANCELED (note: callback is run asynchronously). + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| dlgClass | string | The class name identifier for the dialog. | +| [buttonId] | string | The button id to use when closing the dialog. Defaults to DIALOG_CANCELED | + + + +## addLinkTooltips(elementOrDialog) +Ensures that all tags with a URL have a tooltip showing the same URL + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| elementOrDialog | jQueryObject \| [Dialog](#new_Dialog_new) | Dialog intance, or root of other DOM tree to add tooltips to | + diff --git a/docs/API-Reference/widgets/DropdownButton.md b/docs/API-Reference/widgets/DropdownButton.md index cb73a16e97..6472536096 100644 --- a/docs/API-Reference/widgets/DropdownButton.md +++ b/docs/API-Reference/widgets/DropdownButton.md @@ -52,6 +52,8 @@ DropdownButton dispatches the following events: * [DropdownButton(label, items, [itemRenderer], [options])](#DropdownButton) * [.items](#DropdownButton+items) : Array.<\*> * [.itemsSearchFilterText](#DropdownButton+itemsSearchFilterText) : null + * [.$button](#DropdownButton+$button) : jQueryObject + * [.$dropdown](#DropdownButton+$dropdown) : jQueryObject * [.dropdownExtraClasses](#DropdownButton+dropdownExtraClasses) : string * [.setButtonLabel(label)](#DropdownButton+setButtonLabel) * [.isOpen()](#DropdownButton+isOpen) @@ -75,6 +77,18 @@ Items in dropdown list - may be changed any time dropdown isn't open This is filter text corresponding to each items. it will be used to filter the items based on the keyboard key presses the user does to enter search filter in popup. +**Kind**: instance property of [DropdownButton](#DropdownButton) + + +### dropdownButton.$button : jQueryObject +The clickable button. Available as soon as the DropdownButton is constructed. + +**Kind**: instance property of [DropdownButton](#DropdownButton) + + +### dropdownButton.$dropdown : jQueryObject +The dropdown element. Only non-null while open. + **Kind**: instance property of [DropdownButton](#DropdownButton) diff --git a/docs/API-Reference/widgets/NotificationUI.md b/docs/API-Reference/widgets/NotificationUI.md index f19eb4f6fe..0d5fee0217 100644 --- a/docs/API-Reference/widgets/NotificationUI.md +++ b/docs/API-Reference/widgets/NotificationUI.md @@ -46,8 +46,8 @@ The `createFromTemplate` API can be configured with numerous options. See API op * [widgets/NotificationUI](#module_widgets/NotificationUI) * [.API](#module_widgets/NotificationUI..API) - * [.NOTIFICATION_STYLES_CSS_CLASS](#module_widgets/NotificationUI..NOTIFICATION_STYLES_CSS_CLASS) : object - * [.CLOSE_REASON](#module_widgets/NotificationUI..CLOSE_REASON) : object + * [.NOTIFICATION_STYLES_CSS_CLASS](#module_widgets/NotificationUI..NOTIFICATION_STYLES_CSS_CLASS) : enum + * [.CLOSE_REASON](#module_widgets/NotificationUI..CLOSE_REASON) : enum * [.createFromTemplate(template, [elementID], [options])](#module_widgets/NotificationUI..createFromTemplate) ⇒ Notification * [.createToastFromTemplate(title, template, [options])](#module_widgets/NotificationUI..createToastFromTemplate) ⇒ Notification @@ -59,16 +59,34 @@ This section outlines the properties and methods available in this module **Kind**: inner property of [widgets/NotificationUI](#module_widgets/NotificationUI) -### widgets/NotificationUI.NOTIFICATION\_STYLES\_CSS\_CLASS : object +### widgets/NotificationUI.NOTIFICATION\_STYLES\_CSS\_CLASS : enum CSS class names for notification styles. -**Kind**: inner constant of [widgets/NotificationUI](#module_widgets/NotificationUI) +**Kind**: inner enum of [widgets/NotificationUI](#module_widgets/NotificationUI) +**Properties** + +| Name | Type | Default | +| --- | --- | --- | +| INFO | string | "style-info" | +| WARNING | string | "style-warning" | +| SUCCESS | string | "style-success" | +| ERROR | string | "style-error" | +| DANGER | string | "style-danger" | + -### widgets/NotificationUI.CLOSE\_REASON : object +### widgets/NotificationUI.CLOSE\_REASON : enum Closing notification reason. -**Kind**: inner constant of [widgets/NotificationUI](#module_widgets/NotificationUI) +**Kind**: inner enum of [widgets/NotificationUI](#module_widgets/NotificationUI) +**Properties** + +| Name | Type | Default | +| --- | --- | --- | +| TIMEOUT | string | "closeTimeout" | +| CLICK_DISMISS | string | "clickDismiss" | +| CLOSE_BTN_CLICK | string | "closeBtnClick" | + ### widgets/NotificationUI.createFromTemplate(template, [elementID], [options]) ⇒ Notification diff --git a/src/widgets/DefaultDialogs.js b/src/widgets/DefaultDialogs.js index 440f066a98..d7e6b2eaca 100644 --- a/src/widgets/DefaultDialogs.js +++ b/src/widgets/DefaultDialogs.js @@ -19,16 +19,50 @@ * */ +// @INCLUDE_IN_API_DOCS + define(function (require, exports, module) { + /** + * Constants representing dialog IDs + * These IDs are used to identify different types of dialogs + * + * @module DefaultDialogs + */ + + /** + * ID for error dialog + * @constant {string} + */ + exports.DIALOG_ID_ERROR = "error-dialog"; + + /** + * ID for information dialog (currently uses the same template as DIALOG_ID_ERROR) + * @constant {string} + */ + exports.DIALOG_ID_INFO = "error-dialog"; // uses the same template for now--could be different in future + + /** + * ID for save and close dialog + * @constant {string} + */ + exports.DIALOG_ID_SAVE_CLOSE = "save-close-dialog"; + + /** + * ID for `external change detected` dialog + * @constant {string} + */ + exports.DIALOG_ID_EXT_CHANGED = "ext-changed-dialog"; + + /** + * ID for `external deletion detected` dialog + * @constant {string} + */ + exports.DIALOG_ID_EXT_DELETED = "ext-deleted-dialog"; /** - * List of constants for the default dialogs IDs. + * ID for `change extensions` dialog + * @constant {string} */ - exports.DIALOG_ID_ERROR = "error-dialog"; - exports.DIALOG_ID_INFO = "error-dialog"; // uses the same template for now--could be different in future - exports.DIALOG_ID_SAVE_CLOSE = "save-close-dialog"; - exports.DIALOG_ID_EXT_CHANGED = "ext-changed-dialog"; - exports.DIALOG_ID_EXT_DELETED = "ext-deleted-dialog"; exports.DIALOG_ID_CHANGE_EXTENSIONS = "change-marked-extensions"; }); diff --git a/src/widgets/Dialogs.js b/src/widgets/Dialogs.js index 691408d026..cf24836dab 100644 --- a/src/widgets/Dialogs.js +++ b/src/widgets/Dialogs.js @@ -19,6 +19,8 @@ * */ +// @INCLUDE_IN_API_DOCS + /** * Utilities for creating and managing standard modal dialogs. */ @@ -38,27 +40,72 @@ define(function (require, exports, module) { Mustache = require("thirdparty/mustache/mustache"); /** - * Dialog Buttons IDs - * @const {string} + * `CANCEL` dialog button ID + * @type {string} + * @const + */ + let DIALOG_BTN_CANCEL = "cancel"; + + /** + * `OK` dialog button ID + * @type {string} + * @const + */ + let DIALOG_BTN_OK = "ok"; + + /** + * `DONT SAVE` dialog button ID + * @type {string} + * @const + */ + let DIALOG_BTN_DONTSAVE = "dontsave"; + + /** + * `SAVE AS` dialog button ID + * @type {string} + * @const + */ + let DIALOG_BTN_SAVE_AS = "save_as"; + + /** + * `CANCELED` dialog button ID + * @type {string} + * @const + */ + let DIALOG_CANCELED = "_canceled"; + + /** + * `DOWNLOAD` dialog button ID + * @type {string} + * @const + */ + let DIALOG_BTN_DOWNLOAD = "download"; + + /** + * Primary button class name + * @type {string} + * @const + */ + let DIALOG_BTN_CLASS_PRIMARY = "primary"; + + /** + * Normal button class name + * @type {string} + * @const */ - let DIALOG_BTN_CANCEL = "cancel", - DIALOG_BTN_OK = "ok", - DIALOG_BTN_DONTSAVE = "dontsave", - DIALOG_BTN_SAVE_AS = "save_as", - DIALOG_CANCELED = "_canceled", - DIALOG_BTN_DOWNLOAD = "download"; + let DIALOG_BTN_CLASS_NORMAL = ""; /** - * Dialog Buttons Class Names - * @const {string} + * Left-aligned button class name + * @type {string} + * @const */ - let DIALOG_BTN_CLASS_PRIMARY = "primary", - DIALOG_BTN_CLASS_NORMAL = "", - DIALOG_BTN_CLASS_LEFT = "left"; + let DIALOG_BTN_CLASS_LEFT = "left"; /** * The z-index used for the dialogs. Each new dialog increase this number by 2 * @type {number} + * @private */ let zIndex = 1050; @@ -74,7 +121,7 @@ define(function (require, exports, module) { /** * @private - * Dismises a modal dialog + * Dismisses a modal dialog * @param {$.Element} $dlg * @param {string} buttonId */ @@ -151,6 +198,7 @@ define(function (require, exports, module) { /** * Handles the keyDown event for the dialogs + * @private * @param {$.Event} e * @param {boolean} autoDismiss * @return {boolean} @@ -240,6 +288,7 @@ define(function (require, exports, module) { /** * The dialog jQuery element * @type {$.Element} + * @private */ Dialog.prototype.getElement = function () { return this._$dlg; @@ -248,7 +297,7 @@ define(function (require, exports, module) { /** * Determines whether the dialog is currently shown. Note that even if other dialogs occlude this dialog when * multiple dialogs are shown, this will still return true. - * + * @private * @returns {boolean} true if the dialog is visible, false otherwise. */ Dialog.prototype.isVisible = function () { @@ -257,6 +306,7 @@ define(function (require, exports, module) { /** * The dialog promise + * @private * @type {$.Promise} */ Dialog.prototype.getPromise = function () { @@ -265,6 +315,7 @@ define(function (require, exports, module) { /** * Closes the dialog if is visible + * @private */ Dialog.prototype.close = function () { if (this._$dlg.is(":visible")) { // Bootstrap breaks if try to hide dialog that's already hidden @@ -274,6 +325,7 @@ define(function (require, exports, module) { /** * Adds a done callback to the dialog promise + * @private */ Dialog.prototype.done = function (callback) { this._promise.done(callback); @@ -282,6 +334,7 @@ define(function (require, exports, module) { /** * Don't allow dialog to exceed viewport size + * @private */ function setDialogMaxSize() { let maxWidth, maxHeight, @@ -435,6 +488,14 @@ define(function (require, exports, module) { return showModalDialogUsingTemplate(template, autoDismiss); } + /** + * Display a confirmation dialog with `OK` and `CANCEL` button + * + * @param {string} title dialog title + * @param {string} message message to display in the dialog + * @param {boolean=} autoDismiss whether to automatically dismiss the dialog or not + * @return {Dialog} the created dialog instance + */ function showConfirmDialog(title, message, autoDismiss) { const buttons = [ { className: DIALOG_BTN_CLASS_NORMAL, id: DIALOG_BTN_CANCEL, text: Strings.CANCEL }, @@ -444,10 +505,26 @@ define(function (require, exports, module) { return showModalDialog(DefaultDialogs.DIALOG_ID_INFO, title, message, buttons, autoDismiss); } + /** + * Display information dialog + * + * @param {string} title dialog title + * @param {string} message message to display in the dialog + * @param {boolean=} autoDismiss whether to automatically dismiss the dialog or not + * @return {Dialog} the created dialog instance + */ function showInfoDialog(title, message, autoDismiss) { return showModalDialog(DefaultDialogs.DIALOG_ID_INFO, title, message, null, autoDismiss); } + /** + * Display error dialog + * + * @param {string} title dialog title + * @param {string} message message to display in the dialog + * @param {boolean=} autoDismiss whether to automatically dismiss the dialog or not + * @return {Dialog} the created dialog instance + */ function showErrorDialog(title, message, autoDismiss) { return showModalDialog(DefaultDialogs.DIALOG_ID_ERROR, title, message, null, autoDismiss); } diff --git a/src/widgets/DropdownButton.js b/src/widgets/DropdownButton.js index b9f53de243..cf776becfa 100644 --- a/src/widgets/DropdownButton.js +++ b/src/widgets/DropdownButton.js @@ -131,14 +131,12 @@ define(function (require, exports, module) { /** * The clickable button. Available as soon as the DropdownButton is constructed. - * @private * @type {!jQueryObject} */ DropdownButton.prototype.$button = null; /** * The dropdown element. Only non-null while open. - * @private * @type {?jQueryObject} */ DropdownButton.prototype.$dropdown = null; diff --git a/src/widgets/NotificationUI.js b/src/widgets/NotificationUI.js index f5f3c03b2f..eb098459f6 100644 --- a/src/widgets/NotificationUI.js +++ b/src/widgets/NotificationUI.js @@ -75,7 +75,7 @@ define(function (require, exports, module) { /** * CSS class names for notification styles. - * @type {object} + * @enum {string} * @const */ const NOTIFICATION_STYLES_CSS_CLASS = { @@ -88,7 +88,7 @@ define(function (require, exports, module) { /** * Closing notification reason. - * @type {object} + * @enum {string} * @const */ const CLOSE_REASON ={