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 Utils dir #1917

Closed
wants to merge 3 commits into from
Closed

docs: refine API docs for files in Utils dir #1917

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7bdfca5
docs: refine API docs for files in Utils dir
devvaannsh Oct 27, 2024
c7ae639
docs: add new files to API docs, and fix jsdoc issues
devvaannsh Oct 29, 2024
c6efef5
Merge branch 'phcode-dev:main' into utils
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
39 changes: 35 additions & 4 deletions docs/API-Reference/utils/AppInit.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,42 @@ const AppInit = brackets.getModule("utils/AppInit")
<a name="Metrics"></a>

## Metrics
Defines hooks to assist with module initialization.This module defines 3 methods for client modules to attach callbacks: - htmlReady - When the main application template is rendered - extensionsLoaded - When the extension manager has loaded all extensions - appReady - When Brackets completes loading all modules and extensionsThese are *not* jQuery events. Each method is similar to $(document).readyin that it will call the handler immediately if brackets is already doneloading.
Defines hooks to assist with module initialization.

This module defines 3 methods for client modules to attach callbacks:
- htmlReady - When the main application template is rendered
- extensionsLoaded - When the extension manager has loaded all extensions
- appReady - When Brackets completes loading all modules and extensions

These are *not* jQuery events. Each method is similar to $(document).ready
in that it will call the handler immediately if brackets is already done
loading.

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

## HTML\_READY : <code>string</code>
Fires when the base htmlContent/main-view.html is loaded

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

## APP\_READY : <code>string</code>
Fires when all extensions are loaded

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

## EXTENSIONS\_LOADED : <code>string</code>
Fires after extensions have been loaded

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

## appReady(handler)
Adds a callback for the ready hook. Handlers are called afterhtmlReady is done, the initial project is loaded, and all extensions areloaded.
Adds a callback for the ready hook. Handlers are called after
htmlReady is done, the initial project is loaded, and all extensions are
loaded.

**Kind**: global function

Expand All @@ -23,7 +52,8 @@ Adds a callback for the ready hook. Handlers are called after htmlReady is done,
<a name="htmlReady"></a>

## htmlReady(handler)
Adds a callback for the htmlReady hook. Handlers are called after themain application html template is rendered.
Adds a callback for the htmlReady hook. Handlers are called after the
main application html template is rendered.

**Kind**: global function

Expand All @@ -34,7 +64,8 @@ Adds a callback for the htmlReady hook. Handlers are called after the main appli
<a name="extensionsLoaded"></a>

## extensionsLoaded(handler)
Adds a callback for the extensionsLoaded hook. Handlers are called after theextensions have been loaded
Adds a callback for the extensionsLoaded hook. Handlers are called after the
extensions have been loaded

**Kind**: global function

Expand Down
21 changes: 19 additions & 2 deletions docs/API-Reference/utils/ColorUtils.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,29 @@ const ColorUtils = brackets.getModule("utils/ColorUtils")
<a name="@type"></a>

## @type : <code>Array</code>
Sorted array of all the color names in the CSS Color Module Level 3 (http://www.w3.org/TR/css3-color/)and "rebeccapurple" from CSS Color Module Level 4
Sorted array of all the color names in the CSS Color Module Level 3 (http://www.w3.org/TR/css3-color/)
and "rebeccapurple" from CSS Color Module Level 4

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

## @type : <code>RegExp</code>
Regular expression that matches reasonably well-formed colors in hex format (3 or 6 digits),rgb()/rgba() function format, hsl()/hsla() function format, 0x notation formator color name format according to CSS Color Module Level 3 (http://www.w3.org/TR/css3-color/)or "rebeccapurple" from CSS Color Module Level 4.
Regular expression that matches reasonably well-formed colors in hex format (3 or 6 digits),
rgb()/rgba() function format, hsl()/hsla() function format, 0x notation format
or color name format according to CSS Color Module Level 3 (http://www.w3.org/TR/css3-color/)
or "rebeccapurple" from CSS Color Module Level 4.

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

## formatColorHint($hintObj, color) ⇒ <code>jQuery</code>
Adds a color swatch to code hints where this is supported.

**Kind**: global function
**Returns**: <code>jQuery</code> - jQuery object with the correct class and/or style applied

| Param | Type | Description |
| --- | --- | --- |
| $hintObj | <code>jQuery</code> | list item where the swatch will be in |
| color | <code>string</code> | color the swatch should have, or null to add extra left margin to align with the other hints |

20 changes: 12 additions & 8 deletions docs/API-Reference/utils/DeprecationWarning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,11 @@ const DeprecationWarning = brackets.getModule("utils/DeprecationWarning")
Utilities functions to display deprecation warning in the console.

**Kind**: global variable
<a name="_trimStack"></a>

## \_trimStack()
Trim the stack so that it does not have the call to this module,and all the calls to require.js to load the extension that showsthis deprecation warning.

**Kind**: global function
<a name="deprecationWarning"></a>

## deprecationWarning(message, [oncePerCaller], [callerStackPos])
Show deprecation warning with the call stack if ithas never been displayed before.
Show deprecation warning with the call stack if it
has never been displayed before.

**Kind**: global function

Expand All @@ -31,7 +26,16 @@ Show deprecation warning with the call stack if it has never been displayed befo
<a name="deprecateEvent"></a>

## deprecateEvent(outbound, inbound, oldEventName, newEventName, [canonicalOutboundName], [canonicalInboundName])
Show a deprecation warning if there are listeners for the event``` DeprecationWarning.deprecateEvent(exports, MainViewManager, "workingSetAdd", "workingSetAdd", "DocumentManager.workingSetAdd", "MainViewManager.workingSetAdd");```
Show a deprecation warning if there are listeners for the event

```
DeprecationWarning.deprecateEvent(exports,
MainViewManager,
"workingSetAdd",
"workingSetAdd",
"DocumentManager.workingSetAdd",
"MainViewManager.workingSetAdd");
```

**Kind**: global function

Expand Down
18 changes: 4 additions & 14 deletions docs/API-Reference/utils/DragAndDrop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,25 +15,14 @@ Returns true if the drag and drop items contains valid drop objects.
| --- | --- | --- |
| items | <code>Array.&lt;DataTransferItem&gt;</code> | Array of items being dragged |

<a name="stopURIListPropagation"></a>

## stopURIListPropagation(files, event)
Determines if the event contains a type list that has a URI-list.If it does and contains an empty file list, then what is being dropped is a URL.If that is true then we stop the event propagation and default behavior to save Brackets editor from the browser taking over.

**Kind**: global function

| Param | Type | Description |
| --- | --- | --- |
| files | <code>Array.&lt;File&gt;</code> | Array of File objects from the event datastructure. URLs are the only drop item that would contain a URI-list. |
| event | <code>event</code> | The event datastucture containing datatransfer information about the drag/drop event. Contains a type list which may or may not hold a URI-list depending on what was dragged/dropped. Interested if it does. |

<a name="openDroppedFiles"></a>

## openDroppedFiles(files) ⇒ <code>Promise</code>
Open dropped files

**Kind**: global function
**Returns**: <code>Promise</code> - Promise that is resolved if all files are opened, or rejected if there was an error.
**Returns**: <code>Promise</code> - Promise that is resolved if all files are opened, or rejected
if there was an error.

| Param | Type | Description |
| --- | --- | --- |
Expand All @@ -42,6 +31,7 @@ Open dropped files
<a name="attachHandlers"></a>

## attachHandlers()
Attaches global drag & drop handlers to this window. This enables dropping files/folders to open them, and alsoprotects the Brackets app from being replaced by the browser trying to load the dropped file in its place.
Attaches global drag & drop handlers to this window. This enables dropping files/folders to open them, and also
protects the Brackets app from being replaced by the browser trying to load the dropped file in its place.

**Kind**: global function
95 changes: 16 additions & 79 deletions docs/API-Reference/utils/DropdownEventHandler.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,21 +11,28 @@ const DropdownEventHandler = brackets.getModule("utils/DropdownEventHandler")
* [DropdownEventHandler](#DropdownEventHandler)
* [new DropdownEventHandler($list, selectionCallback, closeCallback, keyDownCallback)](#new_DropdownEventHandler_new)
* [.open()](#DropdownEventHandler+open)
* [._keydownHook(event)](#DropdownEventHandler+open.._keydownHook) ⇒ <code>boolean</code>
* [.closeCallback()](#DropdownEventHandler+open..closeCallback)
* [.close()](#DropdownEventHandler+close)
* [._cleanup()](#DropdownEventHandler+_cleanup)
* [._tryToSelect(index, direction, [noWrap])](#DropdownEventHandler+_tryToSelect)
* [._itemsPerPage()](#DropdownEventHandler+_itemsPerPage) ⇒ <code>number</code>
* [._selectionHandler()](#DropdownEventHandler+_selectionHandler)
* [._clickHandler($item)](#DropdownEventHandler+_clickHandler)
* [._registerMouseEvents()](#DropdownEventHandler+_registerMouseEvents)
* [.reRegisterMouseHandlers($list)](#DropdownEventHandler+reRegisterMouseHandlers)

<a name="new_DropdownEventHandler_new"></a>

### new DropdownEventHandler($list, selectionCallback, closeCallback, keyDownCallback)
Object to handle events for a dropdown list.DropdownEventHandler handles these events:Mouse:- click - execute selection callback and dismiss list- mouseover - highlight item- mouseleave - remove mouse highlightingKeyboard:- Enter - execute selection callback and dismiss list- Esc - dismiss list- Up/Down - change selection- PageUp/Down - change selectionItems whose "a" has the .disabled class do not respond to selection.
Object to handle events for a dropdown list.

DropdownEventHandler handles these events:

Mouse:
- click - execute selection callback and dismiss list
- mouseover - highlight item
- mouseleave - remove mouse highlighting

Keyboard:
- Enter - execute selection callback and dismiss list
- Esc - dismiss list
- Up/Down - change selection
- PageUp/Down - change selection

Items whose "a" has the .disabled class do not respond to selection.


| Param | Type | Description |
Expand All @@ -41,81 +48,11 @@ Object to handle events for a dropdown list. DropdownEventHandler handles these
Public open method

**Kind**: instance method of [<code>DropdownEventHandler</code>](#DropdownEventHandler)

* [.open()](#DropdownEventHandler+open)
* [._keydownHook(event)](#DropdownEventHandler+open.._keydownHook) ⇒ <code>boolean</code>
* [.closeCallback()](#DropdownEventHandler+open..closeCallback)

<a name="DropdownEventHandler+open.._keydownHook"></a>

#### open.\_keydownHook(event) ⇒ <code>boolean</code>
Convert keydown events into hint list navigation actions.

**Kind**: inner method of [<code>open</code>](#DropdownEventHandler+open)
**Returns**: <code>boolean</code> - true if key was handled, otherwise false.

| Param | Type |
| --- | --- |
| event | <code>KeyboardEvent</code> |

<a name="DropdownEventHandler+open..closeCallback"></a>

#### open.closeCallback()
PopUpManager callback

**Kind**: inner method of [<code>open</code>](#DropdownEventHandler+open)
<a name="DropdownEventHandler+close"></a>

### dropdownEventHandler.close()
Public close method

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

### dropdownEventHandler.\_cleanup()
Cleanup

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

### dropdownEventHandler.\_tryToSelect(index, direction, [noWrap])
Try to select item at the given index. If it's disabled or a divider, keep trying by incrementingindex by 'direction' each time (wrapping around if needed).

**Kind**: instance method of [<code>DropdownEventHandler</code>](#DropdownEventHandler)

| Param | Type | Description |
| --- | --- | --- |
| index | <code>number</code> | If out of bounds, index either wraps around to remain in range (e.g. -1 yields last item, length+1 yields 2nd item) or if noWrap set, clips instead (e.g. -1 yields first item, length+1 yields last item). |
| direction | <code>number</code> | Either +1 or -1 |
| [noWrap] | <code>boolean</code> | Clip out of range index values instead of wrapping. Default false (wrap). |

<a name="DropdownEventHandler+_itemsPerPage"></a>

### dropdownEventHandler.\_itemsPerPage() ⇒ <code>number</code>
**Kind**: instance method of [<code>DropdownEventHandler</code>](#DropdownEventHandler)
**Returns**: <code>number</code> - The number of items per scroll page.
<a name="DropdownEventHandler+_selectionHandler"></a>

### dropdownEventHandler.\_selectionHandler()
Call selectionCallback with selected index

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

### dropdownEventHandler.\_clickHandler($item)
Call selectionCallback with selected item

**Kind**: instance method of [<code>DropdownEventHandler</code>](#DropdownEventHandler)

| Param | Type |
| --- | --- |
| $item | <code>jQueryObject</code> |

<a name="DropdownEventHandler+_registerMouseEvents"></a>

### dropdownEventHandler.\_registerMouseEvents()
Register mouse event handlers

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

Expand Down
Loading
Loading