From 0af0d129e7125845a4ec62f9fc72f627b1c22988 Mon Sep 17 00:00:00 2001 From: Pluto Date: Mon, 28 Oct 2024 18:07:03 +0530 Subject: [PATCH] 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 accbe5b8f..cb73a16e9 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 284467cbc..f69cbe672 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 447a210b5..f19eb4f6f 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 e4bfa33ed..5c28bdd67 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 27f7a2bbd..b9f53de24 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 27dbbc60a..e33dcc35f 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 10e915023..f5f3c03b2 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 1357b7788..d90b319db 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();