Skip to content

Commit

Permalink
docs: refine API docs for files in Widgets dir
Browse files Browse the repository at this point in the history
  • Loading branch information
@devvaannsh
devvaannsh committed Oct 28, 2024
1 parent 085a4a4 commit 0af0d12
Show file tree
Hide file tree
Showing 8 changed files with 186 additions and 95 deletions.
67 changes: 36 additions & 31 deletions docs/API-Reference/widgets/DropdownButton.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,38 @@
const DropdownButton = brackets.getModule("widgets/DropdownButton")
```

<a name="EVENT_SELECTED"></a>

## EVENT\_SELECTED : <code>string</code>
Event triggered when an item is selected.

**Kind**: global constant
<a name="EVENT_LIST_RENDERED"></a>

## EVENT\_LIST\_RENDERED : <code>string</code>
Event triggered when the list is rendered.

**Kind**: global constant
<a name="EVENT_DROPDOWN_SHOWN"></a>

## EVENT\_DROPDOWN\_SHOWN : <code>string</code>
Event triggered when the dropdown is shown.

**Kind**: global constant
<a name="EVENT_DROPDOWN_CLOSED"></a>

## EVENT\_DROPDOWN\_CLOSED : <code>string</code>
Event triggered when the dropdown is closed.

**Kind**: global constant
<a name="DropdownButton"></a>

## DropdownButton(label, items, [itemRenderer], [options])
Creates a single dropdown-button instance. The DOM node is created but not attached tothe 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

Expand All @@ -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) : <code>Array.&lt;\*&gt;</code>
* [.itemsSearchFilterText](#DropdownButton+itemsSearchFilterText) : <code>null</code>
* [.$button](#DropdownButton+$button) : <code>jQueryObject</code>
* [.$dropdown](#DropdownButton+$dropdown) : <code>jQueryObject</code>
* [.dropdownExtraClasses](#DropdownButton+dropdownExtraClasses) : <code>string</code>
* [.setButtonLabel(label)](#DropdownButton+setButtonLabel)
* [.isOpen()](#DropdownButton+isOpen)
* [.itemRenderer(item, index)](#DropdownButton+itemRenderer) ⇒ <code>string</code> \| <code>Object</code>
* [._renderList($parent)](#DropdownButton+_renderList) ⇒ <code>jQueryObject</code>
* [.refresh()](#DropdownButton+refresh)
* [.setChecked(index, checked)](#DropdownButton+setChecked)
* [.showDropdown()](#DropdownButton+showDropdown)
Expand All @@ -47,19 +72,8 @@ Items in dropdown list - may be changed any time dropdown isn't open
<a name="DropdownButton+itemsSearchFilterText"></a>

### dropdownButton.itemsSearchFilterText : <code>null</code>
This is filter text corresponding to each items. it will be used to filter the items based onthe keyboard key presses the user does to enter search filter in popup.

**Kind**: instance property of [<code>DropdownButton</code>](#DropdownButton)
<a name="DropdownButton+$button"></a>

### dropdownButton.$button : <code>jQueryObject</code>
The clickable button. Available as soon as the DropdownButton is constructed.

**Kind**: instance property of [<code>DropdownButton</code>](#DropdownButton)
<a name="DropdownButton+$dropdown"></a>

### dropdownButton.$dropdown : <code>jQueryObject</code>
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 [<code>DropdownButton</code>](#DropdownButton)
<a name="DropdownButton+dropdownExtraClasses"></a>
Expand Down Expand Up @@ -91,29 +105,20 @@ returns true if the dropdown is open
Called for each item when rendering the dropdown.

**Kind**: instance method of [<code>DropdownButton</code>](#DropdownButton)
**Returns**: <code>string</code> \| <code>Object</code> - 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**: <code>string</code> \| <code>Object</code> - 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 | <code>\*</code> | from items array |
| index | <code>number</code> | in items array |

<a name="DropdownButton+_renderList"></a>

### dropdownButton.\_renderList($parent) ⇒ <code>jQueryObject</code>
Converts the list of item objects into HTML list items in format required by DropdownEventHandler

**Kind**: instance method of [<code>DropdownButton</code>](#DropdownButton)
**Returns**: <code>jQueryObject</code> - The dropdown element with the rendered list items appended.

| Param | Type | Description |
| --- | --- | --- |
| $parent | <code>jQueryObject</code> | The dropdown element |

<a name="DropdownButton+refresh"></a>

### 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 [<code>DropdownButton</code>](#DropdownButton)
<a name="DropdownButton+setChecked"></a>
Expand Down
54 changes: 21 additions & 33 deletions docs/API-Reference/widgets/ModalBar.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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) : <code>function</code>
* [.height()](#ModalBar+height) ⇒ <code>number</code>
* [.prepareClose([restoreScrollPos])](#ModalBar+prepareClose)
* [.close([restoreScrollPos], [animate], [_reason])](#ModalBar+close) ⇒ <code>$.Promise</code>
* [._handleKeydown()](#ModalBar+_handleKeydown)
* [._handleFocusChange()](#ModalBar+_handleFocusChange)
* [.getRoot()](#ModalBar+getRoot) ⇒ <code>jQueryObject</code>

<a name="new_ModalBar_new"></a>

### 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 |
Expand All @@ -32,22 +36,12 @@ Creates a modal bar whose contents are the given template. Dispatches one event
| autoClose | <code>boolean</code> | If true, then close the dialog if the user hits Esc or if the bar loses focus. |
| animate | <code>boolean</code> | If true (the default), animate the dialog closed, otherwise close it immediately. |

<a name="ModalBar+_$root"></a>

### modalBar.\_$root
A jQuery object containing the root node of the ModalBar.

**Kind**: instance property of [<code>ModalBar</code>](#ModalBar)
<a name="ModalBar+_autoClose"></a>

### modalBar.\_autoClose
True if this ModalBar is set to autoclose.

**Kind**: instance property of [<code>ModalBar</code>](#ModalBar)
<a name="ModalBar+isLockedOpen"></a>

### modalBar.isLockedOpen : <code>function</code>
Allows client code to block autoClose from closing the ModalBar: if set, this function is called wheneverautoClose would normally close the ModalBar. Returning true prevents the close from occurring. Programmaticallycalling 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 [<code>ModalBar</code>](#ModalBar)
<a name="ModalBar+height"></a>
Expand All @@ -58,7 +52,11 @@ Allows client code to block autoClose from closing the ModalBar: if set, this fu
<a name="ModalBar+prepareClose"></a>

### 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 ifyou want to do that as a separate operation from actually animating the ModalBarclosed 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 [<code>ModalBar</code>](#ModalBar)

Expand All @@ -69,7 +67,8 @@ Prepares the ModalBar for closing by popping it out of the main flow and resizin
<a name="ModalBar+close"></a>

### modalBar.close([restoreScrollPos], [animate], [_reason]) ⇒ <code>$.Promise</code>
Closes the modal bar and returns focus to the active editor. Returns a promise that isresolved 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 [<code>ModalBar</code>](#ModalBar)
**Returns**: <code>$.Promise</code> - promise resolved when close is finished
Expand All @@ -80,18 +79,6 @@ Closes the modal bar and returns focus to the active editor. Returns a promise t
| [animate] | <code>boolean</code> | If true (the default), animate the closing of the ModalBar, otherwise close it immediately. |
| [_reason] | <code>string</code> | For internal use only. |

<a name="ModalBar+_handleKeydown"></a>

### modalBar.\_handleKeydown()
If autoClose is set, close the bar when Escape is pressed

**Kind**: instance method of [<code>ModalBar</code>](#ModalBar)
<a name="ModalBar+_handleFocusChange"></a>

### modalBar.\_handleFocusChange()
If autoClose is set, detects when something other than the modal bar is getting focus anddismisses the modal bar. DOM nodes with "attached-to" jQuery metadata referencing an elementwithin the ModalBar are allowed to take focus without closing it.

**Kind**: instance method of [<code>ModalBar</code>](#ModalBar)
<a name="ModalBar+getRoot"></a>

### modalBar.getRoot() ⇒ <code>jQueryObject</code>
Expand All @@ -100,6 +87,7 @@ If autoClose is set, detects when something other than the modal bar is getting
<a name="MainViewManager"></a>

## MainViewManager
A "modal bar" component. This is a lightweight replacement for modal dialogs thatappears 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
80 changes: 75 additions & 5 deletions docs/API-Reference/widgets/NotificationUI.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,48 @@ const NotificationUI = brackets.getModule("widgets/NotificationUI")
<a name="module_widgets/NotificationUI"></a>

## 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 exampleFor 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**
```jsconst 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 exampleAnother 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( "<div>Click me to locate the file in file tree</div>", "showInfileTree",{ allowedPlacements: ['top', 'bottom'], dismissOnClick: false, autoCloseTimeS: 300 // auto close the popup after 5 minutes });// do stuffnotification1.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(
"<div>Click me to locate the file in file tree</div>", "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) : <code>object</code>
* [.CLOSE_REASON](#module_widgets/NotificationUI..CLOSE_REASON) : <code>object</code>
* [.createFromTemplate(template, [elementID], [options])](#module_widgets/NotificationUI..createFromTemplate) ⇒ <code>Notification</code>
* [.createToastFromTemplate(title, template, [options])](#module_widgets/NotificationUI..createToastFromTemplate) ⇒ <code>Notification</code>

Expand All @@ -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 [<code>widgets/NotificationUI</code>](#module_widgets/NotificationUI)
<a name="module_widgets/NotificationUI..NOTIFICATION_STYLES_CSS_CLASS"></a>

### widgets/NotificationUI.NOTIFICATION\_STYLES\_CSS\_CLASS : <code>object</code>
CSS class names for notification styles.

**Kind**: inner constant of [<code>widgets/NotificationUI</code>](#module_widgets/NotificationUI)
<a name="module_widgets/NotificationUI..CLOSE_REASON"></a>

### widgets/NotificationUI.CLOSE\_REASON : <code>object</code>
Closing notification reason.

**Kind**: inner constant of [<code>widgets/NotificationUI</code>](#module_widgets/NotificationUI)
<a name="module_widgets/NotificationUI..createFromTemplate"></a>

### widgets/NotificationUI.createFromTemplate(template, [elementID], [options]) ⇒ <code>Notification</code>
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 "<div>Click me to locate the file in file tree</div>", "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
"<div>Click me to locate the file in file tree</div>", "showInfileTree",{
allowedPlacements: ['top', 'bottom'],
dismissOnClick: false,
autoCloseTimeS: 300 // auto close the popup after 5 minutes
});
```

**Kind**: inner method of [<code>widgets/NotificationUI</code>](#module_widgets/NotificationUI)
**Returns**: <code>Notification</code> - Object with a done handler that resolves when the notification closes.
Expand All @@ -41,7 +99,19 @@ Creates a new notification popup from given template. The template can either be
<a name="module_widgets/NotificationUI..createToastFromTemplate"></a>

### widgets/NotificationUI.createToastFromTemplate(title, template, [options]) ⇒ <code>Notification</code>
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 "<div>Click me to locate the file in file tree</div>", { 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
"<div>Click me to locate the file in file tree</div>", {
dismissOnClick: false,
autoCloseTimeS: 300 // auto close the popup after 5 minutes
});
```

**Kind**: inner method of [<code>widgets/NotificationUI</code>](#module_widgets/NotificationUI)
**Returns**: <code>Notification</code> - Object with a done handler that resolves when the notification closes.
Expand Down
Loading

0 comments on commit 0af0d12

Please sign in to comment.