Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: refine API docs for files in Widgets dir #1920

Merged
merged 2 commits into from
Oct 30, 2024
Merged

docs: refine API docs for files in Widgets dir #1920

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0af0d12
docs: refine API docs for files in Widgets dir
devvaannsh Oct 28, 2024
f8fc55f
docs: add new files to API docs and fix mentioned issues
devvaannsh Oct 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions docs/API-Reference/widgets/DefaultDialogs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
### Import :
```js
const DefaultDialogs = brackets.getModule("widgets/DefaultDialogs")
```

<a name="module_DefaultDialogs"></a>

## 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) : <code>string</code>
* [.DIALOG_ID_INFO](#module_DefaultDialogs.DIALOG_ID_INFO) : <code>string</code>
* [.DIALOG_ID_SAVE_CLOSE](#module_DefaultDialogs.DIALOG_ID_SAVE_CLOSE) : <code>string</code>
* [.DIALOG_ID_EXT_CHANGED](#module_DefaultDialogs.DIALOG_ID_EXT_CHANGED) : <code>string</code>
* [.DIALOG_ID_EXT_DELETED](#module_DefaultDialogs.DIALOG_ID_EXT_DELETED) : <code>string</code>
* [.DIALOG_ID_CHANGE_EXTENSIONS](#module_DefaultDialogs.DIALOG_ID_CHANGE_EXTENSIONS) : <code>string</code>

<a name="module_DefaultDialogs.DIALOG_ID_ERROR"></a>

### DefaultDialogs.DIALOG\_ID\_ERROR : <code>string</code>
ID for error dialog

**Kind**: static constant of [<code>DefaultDialogs</code>](#module_DefaultDialogs)
<a name="module_DefaultDialogs.DIALOG_ID_INFO"></a>

### DefaultDialogs.DIALOG\_ID\_INFO : <code>string</code>
ID for information dialog (currently uses the same template as DIALOG_ID_ERROR)

**Kind**: static constant of [<code>DefaultDialogs</code>](#module_DefaultDialogs)
<a name="module_DefaultDialogs.DIALOG_ID_SAVE_CLOSE"></a>

### DefaultDialogs.DIALOG\_ID\_SAVE\_CLOSE : <code>string</code>
ID for save and close dialog

**Kind**: static constant of [<code>DefaultDialogs</code>](#module_DefaultDialogs)
<a name="module_DefaultDialogs.DIALOG_ID_EXT_CHANGED"></a>

### DefaultDialogs.DIALOG\_ID\_EXT\_CHANGED : <code>string</code>
ID for `external change detected` dialog

**Kind**: static constant of [<code>DefaultDialogs</code>](#module_DefaultDialogs)
<a name="module_DefaultDialogs.DIALOG_ID_EXT_DELETED"></a>

### DefaultDialogs.DIALOG\_ID\_EXT\_DELETED : <code>string</code>
ID for `external deletion detected` dialog

**Kind**: static constant of [<code>DefaultDialogs</code>](#module_DefaultDialogs)
<a name="module_DefaultDialogs.DIALOG_ID_CHANGE_EXTENSIONS"></a>

### DefaultDialogs.DIALOG\_ID\_CHANGE\_EXTENSIONS : <code>string</code>
ID for `change extensions` dialog

**Kind**: static constant of [<code>DefaultDialogs</code>](#module_DefaultDialogs)
154 changes: 154 additions & 0 deletions docs/API-Reference/widgets/Dialogs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
### Import :
```js
const Dialogs = brackets.getModule("widgets/Dialogs")
```

<a name="DIALOG_BTN_CANCEL"></a>

## DIALOG\_BTN\_CANCEL : <code>string</code>
`CANCEL` dialog button ID

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

## DIALOG\_BTN\_OK : <code>string</code>
`OK` dialog button ID

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

## DIALOG\_BTN\_DONTSAVE : <code>string</code>
`DONT SAVE` dialog button ID

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

## DIALOG\_BTN\_SAVE\_AS : <code>string</code>
`SAVE AS` dialog button ID

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

## DIALOG\_CANCELED : <code>string</code>
`CANCELED` dialog button ID

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

## DIALOG\_BTN\_DOWNLOAD : <code>string</code>
`DOWNLOAD` dialog button ID

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

## DIALOG\_BTN\_CLASS\_PRIMARY : <code>string</code>
Primary button class name

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

## DIALOG\_BTN\_CLASS\_NORMAL : <code>string</code>
Normal button class name

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

## DIALOG\_BTN\_CLASS\_LEFT : <code>string</code>
Left-aligned button class name

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

## showModalDialogUsingTemplate(template, [autoDismiss]) ⇒ [<code>Dialog</code>](#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 | <code>string</code> | A string template or jQuery object to use as the dialog HTML. |
| [autoDismiss] | <code>boolean</code> | 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. |

<a name="showModalDialog"></a>

## showModalDialog(dlgClass, [title], [message], [buttons], [autoDismiss]) ⇒ [<code>Dialog</code>](#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 | <code>string</code> | A class name identifier for the dialog. Typically one of DefaultDialogs.* |
| [title] | <code>string</code> | The title of the dialog. Can contain HTML markup. Defaults to "". |
| [message] | <code>string</code> | The message to display in the dialog. Can contain HTML markup. Defaults to "". |
| [buttons] | <code>Array.&lt;{className: string, id: string, text: string, tooltip:string}&gt;</code> | 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] | <code>boolean</code> | 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. |

<a name="showConfirmDialog"></a>

## showConfirmDialog(title, message, [autoDismiss]) ⇒ [<code>Dialog</code>](#new_Dialog_new)
Display a confirmation dialog with `OK` and `CANCEL` button

**Kind**: global function
**Returns**: [<code>Dialog</code>](#new_Dialog_new) - the created dialog instance

| Param | Type | Description |
| --- | --- | --- |
| title | <code>string</code> | dialog title |
| message | <code>string</code> | message to display in the dialog |
| [autoDismiss] | <code>boolean</code> | whether to automatically dismiss the dialog or not |

<a name="showInfoDialog"></a>

## showInfoDialog(title, message, [autoDismiss]) ⇒ [<code>Dialog</code>](#new_Dialog_new)
Display information dialog

**Kind**: global function
**Returns**: [<code>Dialog</code>](#new_Dialog_new) - the created dialog instance

| Param | Type | Description |
| --- | --- | --- |
| title | <code>string</code> | dialog title |
| message | <code>string</code> | message to display in the dialog |
| [autoDismiss] | <code>boolean</code> | whether to automatically dismiss the dialog or not |

<a name="showErrorDialog"></a>

## showErrorDialog(title, message, [autoDismiss]) ⇒ [<code>Dialog</code>](#new_Dialog_new)
Display error dialog

**Kind**: global function
**Returns**: [<code>Dialog</code>](#new_Dialog_new) - the created dialog instance

| Param | Type | Description |
| --- | --- | --- |
| title | <code>string</code> | dialog title |
| message | <code>string</code> | message to display in the dialog |
| [autoDismiss] | <code>boolean</code> | whether to automatically dismiss the dialog or not |

<a name="cancelModalDialogIfOpen"></a>

## 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 | <code>string</code> | The class name identifier for the dialog. |
| [buttonId] | <code>string</code> | The button id to use when closing the dialog. Defaults to DIALOG_CANCELED |

<a name="addLinkTooltips"></a>

## addLinkTooltips(elementOrDialog)
Ensures that all <a> tags with a URL have a tooltip showing the same URL

**Kind**: global function

| Param | Type | Description |
| --- | --- | --- |
| elementOrDialog | <code>jQueryObject</code> \| [<code>Dialog</code>](#new_Dialog_new) | Dialog intance, or root of other DOM tree to add tooltips to |

53 changes: 36 additions & 17 deletions docs/API-Reference/widgets/DropdownButton.md
View file
Open in desktop
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 @@ -30,7 +58,6 @@ Creates a single dropdown-button instance. The DOM node is created but not attac
* [.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,7 +74,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.
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+$button"></a>
Expand Down Expand Up @@ -91,29 +119,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
Loading
Loading