Skip to content

Commit

Permalink
docs: refine API docs for files in Utils dir
Browse files Browse the repository at this point in the history
  • Loading branch information
@devvaannsh
devvaannsh committed Oct 27, 2024
1 parent 085a4a4 commit 7bdfca5
Show file tree
Hide file tree
Showing 36 changed files with 768 additions and 550 deletions.
39 changes: 35 additions & 4 deletions docs/API-Reference/utils/AppInit.md
View file
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
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
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
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
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

0 comments on commit 7bdfca5

Please sign in to comment.