diff --git a/docs/API-Reference/utils/AppInit.md b/docs/API-Reference/utils/AppInit.md index 197f7120e5..b867ccc5ad 100644 --- a/docs/API-Reference/utils/AppInit.md +++ b/docs/API-Reference/utils/AppInit.md @@ -6,13 +6,42 @@ const AppInit = brackets.getModule("utils/AppInit") ## 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 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. +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 + + +## HTML\_READY : string +Fires when the base htmlContent/main-view.html is loaded + +**Kind**: global constant + + +## APP\_READY : string +Fires when all extensions are loaded + +**Kind**: global constant + + +## EXTENSIONS\_LOADED : string +Fires after extensions have been loaded **Kind**: global constant ## appReady(handler) -Adds a callback for the ready hook. Handlers are called after htmlReady is done, the initial project is loaded, and all extensions are loaded. +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 @@ -23,7 +52,8 @@ Adds a callback for the ready hook. Handlers are called after htmlReady is done, ## htmlReady(handler) -Adds a callback for the htmlReady hook. Handlers are called after the main 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 @@ -34,7 +64,8 @@ Adds a callback for the htmlReady hook. Handlers are called after the main appli ## extensionsLoaded(handler) -Adds a callback for the extensionsLoaded hook. Handlers are called after the extensions have been loaded +Adds a callback for the extensionsLoaded hook. Handlers are called after the +extensions have been loaded **Kind**: global function diff --git a/docs/API-Reference/utils/Async.md b/docs/API-Reference/utils/Async.md index 35e9d79263..034a541db5 100644 --- a/docs/API-Reference/utils/Async.md +++ b/docs/API-Reference/utils/Async.md @@ -16,12 +16,20 @@ const Async = brackets.getModule("utils/Async") ### new PromiseQueue() -Creates a queue of async operations that will be executed sequentially. Operations can be added to the queue at any time. If the queue is empty and nothing is currently executing when an operation is added, it will execute immediately. Otherwise, it will execute when the last operation currently in the queue has finished. +Creates a queue of async operations that will be executed sequentially. Operations can be added to the +queue at any time. If the queue is empty and nothing is currently executing when an operation is added, +it will execute immediately. Otherwise, it will execute when the last operation currently in the queue +has finished. ### promiseQueue.add(op) -Adds an operation to the queue. If nothing is currently executing, it will execute immediately (and the next operation added to the queue will wait for it to complete). Otherwise, it will wait until the last operation in the queue (or the currently executing operation if nothing is in the queue) is finished. The operation must return a promise that will be resolved or rejected when it's finished; the queue will continue with the next operation regardless of whether the current operation's promise is resolved or rejected. +Adds an operation to the queue. If nothing is currently executing, it will execute immediately (and +the next operation added to the queue will wait for it to complete). Otherwise, it will wait until +the last operation in the queue (or the currently executing operation if nothing is in the queue) is +finished. The operation must return a promise that will be resolved or rejected when it's finished; +the queue will continue with the next operation regardless of whether the current operation's promise +is resolved or rejected. **Kind**: instance method of [PromiseQueue](#PromiseQueue) @@ -37,14 +45,48 @@ Removes all pending promises from the queue. **Kind**: instance method of [PromiseQueue](#PromiseQueue) -## ERROR\_TIMEOUT +## ERROR\_TIMEOUT : Object Value passed to fail() handlers that have been triggered due to withTimeout()'s timeout **Kind**: global variable ## doInParallel(items, beginProcessItem, failFast) ⇒ $.Promise -Executes a series of tasks in parallel, returning a "master" Promise that is resolved once all the tasks have resolved. If one or more tasks fail, behavior depends on the failFast flag: - If true, the master Promise is rejected as soon as the first task fails. The remaining tasks continue to completion in the background. - If false, the master Promise is rejected after all tasks have completed. If nothing fails: (M = master promise; 1-4 = tasks; d = done; F = fail) M ------------d 1 >---d . 2 >------d . 3 >---------d . 4 >------------d With failFast = false: M ------------F 1 >---d . . 2 >------d . . 3 >---------F . 4 >------------d With failFast = true: -- equivalent to $.when() M ---------F 1 >---d . 2 >------d . 3 >---------F 4 >------------d (#4 continues even though master Promise has failed) (Note: if tasks finish synchronously, the behavior is more like failFast=false because you won't get a chance to respond to the master Promise until after all items have been processed) To perform task-specific work after an individual task completes, attach handlers to each Promise before beginProcessItem() returns it. Note: don't use this if individual tasks (or their done/fail handlers) could ever show a user- visible dialog: because they run in parallel, you could show multiple dialogs atop each other. +Executes a series of tasks in parallel, returning a "master" Promise that is resolved once +all the tasks have resolved. If one or more tasks fail, behavior depends on the failFast +flag: + - If true, the master Promise is rejected as soon as the first task fails. The remaining + tasks continue to completion in the background. + - If false, the master Promise is rejected after all tasks have completed. + +If nothing fails: (M = master promise; 1-4 = tasks; d = done; F = fail) + M ------------d + 1 >---d . + 2 >------d . + 3 >---------d . + 4 >------------d + +With failFast = false: + M ------------F + 1 >---d . . + 2 >------d . . + 3 >---------F . + 4 >------------d + +With failFast = true: -- equivalent to $.when() + M ---------F + 1 >---d . + 2 >------d . + 3 >---------F + 4 >------------d (#4 continues even though master Promise has failed) +(Note: if tasks finish synchronously, the behavior is more like failFast=false because you +won't get a chance to respond to the master Promise until after all items have been processed) + +To perform task-specific work after an individual task completes, attach handlers to each +Promise before beginProcessItem() returns it. + +Note: don't use this if individual tasks (or their done/fail handlers) could ever show a user- +visible dialog: because they run in parallel, you could show multiple dialogs atop each other. **Kind**: global function @@ -57,7 +99,36 @@ Executes a series of tasks in parallel, returning a "master" Promise that is res ## doSequentially(items, beginProcessItem, failAndStopFast) ⇒ $.Promise -Executes a series of tasks in serial (task N does not begin until task N-1 has completed). Returns a "master" Promise that is resolved once all the tasks have resolved. If one or more tasks fail, behavior depends on the failAndStopFast flag: - If true, the master Promise is rejected as soon as the first task fails. The remaining tasks are never started (the serial sequence is stopped). - If false, the master Promise is rejected after all tasks have completed. If nothing fails: M ------------d 1 >---d . 2 >--d . 3 >--d . 4 >--d With failAndStopFast = false: M ------------F 1 >---d . . 2 >--d . . 3 >--F . 4 >--d With failAndStopFast = true: M ---------F 1 >---d . 2 >--d . 3 >--F 4 (#4 never runs) To perform task-specific work after an individual task completes, attach handlers to each Promise before beginProcessItem() returns it. +Executes a series of tasks in serial (task N does not begin until task N-1 has completed). +Returns a "master" Promise that is resolved once all the tasks have resolved. If one or more +tasks fail, behavior depends on the failAndStopFast flag: + - If true, the master Promise is rejected as soon as the first task fails. The remaining + tasks are never started (the serial sequence is stopped). + - If false, the master Promise is rejected after all tasks have completed. + +If nothing fails: + M ------------d + 1 >---d . + 2 >--d . + 3 >--d . + 4 >--d + +With failAndStopFast = false: + M ------------F + 1 >---d . . + 2 >--d . . + 3 >--F . + 4 >--d + +With failAndStopFast = true: + M ---------F + 1 >---d . + 2 >--d . + 3 >--F + 4 (#4 never runs) + +To perform task-specific work after an individual task completes, attach handlers to each +Promise before beginProcessItem() returns it. **Kind**: global function @@ -70,7 +141,8 @@ Executes a series of tasks in serial (task N does not begin until task N-1 has c ## doSequentiallyInBackground(items, fnProcessItem, [maxBlockingTime], [idleTime]) ⇒ $.Promise -Executes a series of synchronous tasks sequentially spread over time-slices less than maxBlockingTime. Processing yields by idleTime between time-slices. +Executes a series of synchronous tasks sequentially spread over time-slices less than maxBlockingTime. +Processing yields by idleTime between time-slices. **Kind**: global function @@ -84,7 +156,9 @@ Executes a series of synchronous tasks sequentially spread over time-slices less ## firstSequentially(items, beginProcessItem) ⇒ $.Promise -Executes a series of tasks in serial (task N does not begin until task N-1 has completed). Returns a "master" Promise that is resolved when the first task has resolved. If all tasks fail, the master Promise is rejected. +Executes a series of tasks in serial (task N does not begin until task N-1 has completed). +Returns a "master" Promise that is resolved when the first task has resolved. If all tasks +fail, the master Promise is rejected. **Kind**: global function @@ -96,7 +170,14 @@ Executes a series of tasks in serial (task N does not begin until task N-1 has c ## doInParallel\_aggregateErrors(items, beginProcessItem) ⇒ $.Promise -Executes a series of tasks in parallel, saving up error info from any that fail along the way. Returns a Promise that is only resolved/rejected once all tasks are complete. This is essentially a wrapper around doInParallel(..., false). If one or more tasks failed, the entire "master" promise is rejected at the end - with one argument: an array objects, one per failed task. Each error object contains: - item -- the entry in items whose task failed - error -- the first argument passed to the fail() handler when the task failed +Executes a series of tasks in parallel, saving up error info from any that fail along the way. +Returns a Promise that is only resolved/rejected once all tasks are complete. This is +essentially a wrapper around doInParallel(..., false). + +If one or more tasks failed, the entire "master" promise is rejected at the end - with one +argument: an array objects, one per failed task. Each error object contains: + - item -- the entry in items whose task failed + - error -- the first argument passed to the fail() handler when the task failed **Kind**: global function @@ -108,7 +189,13 @@ Executes a series of tasks in parallel, saving up error info from any that fail ## withTimeout(promise, timeout, [resolveTimeout]) ⇒ $.Promise -Adds timeout-driven termination to a Promise: returns a new Promise that is resolved/rejected when the given original Promise is resolved/rejected, OR is resolved/rejected after the given delay - whichever happens first. If the original Promise is resolved/rejected first, done()/fail() handlers receive arguments piped from the original Promise. If the timeout occurs first instead, then resolve() or fail() (with Async.ERROR_TIMEOUT) is called based on value of resolveTimeout. +Adds timeout-driven termination to a Promise: returns a new Promise that is resolved/rejected when +the given original Promise is resolved/rejected, OR is resolved/rejected after the given delay - +whichever happens first. + +If the original Promise is resolved/rejected first, done()/fail() handlers receive arguments +piped from the original Promise. If the timeout occurs first instead, then resolve() or +fail() (with Async.ERROR_TIMEOUT) is called based on value of resolveTimeout. **Kind**: global function @@ -121,10 +208,25 @@ Adds timeout-driven termination to a Promise: returns a new Promise that is reso ## waitForAll(promises, [failOnReject], [timeout]) ⇒ $.Promise -Allows waiting for all the promises to be either resolved or rejected. Unlike $.when(), it does not call .fail() or .always() handlers on first reject. The caller should take all the precaution to make sure all the promises passed to this function are completed to avoid blocking. If failOnReject is set to true, promise returned by the function will be rejected if at least one of the promises was rejected. The default value is false, which will cause the call to this function to be always successfully resolved. If timeout is specified, the promise will be rejected on timeout as per Async.withTimeout. +Allows waiting for all the promises to be either resolved or rejected. +Unlike $.when(), it does not call .fail() or .always() handlers on first +reject. The caller should take all the precaution to make sure all the +promises passed to this function are completed to avoid blocking. + +If failOnReject is set to true, promise returned by the function will be +rejected if at least one of the promises was rejected. The default value +is false, which will cause the call to this function to be always +successfully resolved. + +If timeout is specified, the promise will be rejected on timeout as per +Async.withTimeout. **Kind**: global function -**Returns**: $.Promise - A Promise which will be resolved once all dependent promises are resolved. It is resolved with an array of results from the successfully resolved dependent promises. The resulting array may not be in the same order or contain as many items as there were promises to wait on and it will contain 'undefined' entries for those promises that resolve without a result. +**Returns**: $.Promise - A Promise which will be resolved once all dependent promises are resolved. + It is resolved with an array of results from the successfully resolved dependent promises. + The resulting array may not be in the same order or contain as many items as there were + promises to wait on and it will contain 'undefined' entries for those promises that resolve + without a result. | Param | Type | Description | | --- | --- | --- | @@ -135,10 +237,15 @@ Allows waiting for all the promises to be either resolved or rejected. Unlike $. ## chain(functions, args) ⇒ jQuery.Promise -Chains a series of synchronous and asynchronous (jQuery promise-returning) functions together, using the result of each successive function as the argument(s) to the next. A promise is returned that resolves with the result of the final call if all calls resolve or return normally. Otherwise, if any of the functions reject or throw, the computation is halted immediately and the promise is rejected with this halting error. +Chains a series of synchronous and asynchronous (jQuery promise-returning) functions +together, using the result of each successive function as the argument(s) to the next. +A promise is returned that resolves with the result of the final call if all calls +resolve or return normally. Otherwise, if any of the functions reject or throw, the +computation is halted immediately and the promise is rejected with this halting error. **Kind**: global function -**Returns**: jQuery.Promise - A promise that resolves with the result of the final call, or rejects with the first error. +**Returns**: jQuery.Promise - A promise that resolves with the result of the final call, or + rejects with the first error. | Param | Type | Description | | --- | --- | --- | @@ -148,10 +255,34 @@ Chains a series of synchronous and asynchronous (jQuery promise-returning) funct ## promisify(obj, method, ...varargs) ⇒ $.Promise -Utility for converting a method that takes (error, callback) to one that returns a promise; useful for using FileSystem methods (or other Node-style API methods) in a promise-oriented workflow. For example, instead of ```js var deferred = new $.Deferred(); file.read(function (err, contents) { if (err) { deferred.reject(err); } else { // ...process the contents... deferred.resolve(); } } return deferred.promise(); ``` you can just do return Async.promisify(file, "read").then(function (contents) { // ...process the contents... }); The object/method are passed as an object/string pair so that we can properly call the method without the caller having to deal with "bind" all the time. +Utility for converting a method that takes (error, callback) to one that returns a promise; +useful for using FileSystem methods (or other Node-style API methods) in a promise-oriented +workflow. For example, instead of +```js + var deferred = new $.Deferred(); + file.read(function (err, contents) { + if (err) { + deferred.reject(err); + } else { + // ...process the contents... + deferred.resolve(); + } + } + return deferred.promise(); +``` +you can just do + + return Async.promisify(file, "read").then(function (contents) { + // ...process the contents... + }); + +The object/method are passed as an object/string pair so that we can +properly call the method without the caller having to deal with "bind" all the time. **Kind**: global function -**Returns**: $.Promise - A promise that is resolved with the arguments that were passed to the errback (not including the err argument) if err is null, or rejected with the err if non-null. +**Returns**: $.Promise - A promise that is resolved with the arguments that were passed to the + errback (not including the err argument) if err is null, or rejected with the err if + non-null. | Param | Type | Description | | --- | --- | --- | diff --git a/docs/API-Reference/utils/ColorUtils.md b/docs/API-Reference/utils/ColorUtils.md index c9b2688eeb..988a9f5e6e 100644 --- a/docs/API-Reference/utils/ColorUtils.md +++ b/docs/API-Reference/utils/ColorUtils.md @@ -6,12 +6,29 @@ const ColorUtils = brackets.getModule("utils/ColorUtils") ## @type : Array -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 ## @type : RegExp -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. +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 + + +## formatColorHint($hintObj, color) ⇒ jQuery +Adds a color swatch to code hints where this is supported. + +**Kind**: global function +**Returns**: jQuery - jQuery object with the correct class and/or style applied + +| Param | Type | Description | +| --- | --- | --- | +| $hintObj | jQuery | list item where the swatch will be in | +| color | string | color the swatch should have, or null to add extra left margin to align with the other hints | + diff --git a/docs/API-Reference/utils/DeprecationWarning.md b/docs/API-Reference/utils/DeprecationWarning.md index 97803898bb..b7748b84bc 100644 --- a/docs/API-Reference/utils/DeprecationWarning.md +++ b/docs/API-Reference/utils/DeprecationWarning.md @@ -9,16 +9,11 @@ const DeprecationWarning = brackets.getModule("utils/DeprecationWarning") Utilities functions to display deprecation warning in the console. **Kind**: global variable - - -## \_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 shows this deprecation warning. - -**Kind**: global function ## deprecationWarning(message, [oncePerCaller], [callerStackPos]) -Show deprecation warning with the call stack if it has never been displayed before. +Show deprecation warning with the call stack if it +has never been displayed before. **Kind**: global function @@ -31,7 +26,16 @@ Show deprecation warning with the call stack if it has never been displayed befo ## 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 @@ -46,13 +50,14 @@ Show a deprecation warning if there are listeners for the event ``` Deprecat -## deprecateConstant(old, new) +## deprecateConstant(obj, oldId, newId) Create a deprecation warning and action for updated constants **Kind**: global function | Param | Type | Description | | --- | --- | --- | -| old | string | Menu Id | -| new | string | Menu Id | +| obj | Object | | +| oldId | string | Menu Id | +| newId | string | Menu Id | diff --git a/docs/API-Reference/utils/DragAndDrop.md b/docs/API-Reference/utils/DragAndDrop.md index 3f264cee6f..5800006e76 100644 --- a/docs/API-Reference/utils/DragAndDrop.md +++ b/docs/API-Reference/utils/DragAndDrop.md @@ -15,33 +15,23 @@ Returns true if the drag and drop items contains valid drop objects. | --- | --- | --- | | items | Array.<DataTransferItem> | Array of items being dragged | - - -## 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 | Array.<File> | Array of File objects from the event datastructure. URLs are the only drop item that would contain a URI-list. | -| event | event | 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. | - -## openDroppedFiles(files) ⇒ Promise +## openDroppedFiles(paths) ⇒ Promise Open dropped files **Kind**: global function -**Returns**: Promise - Promise that is resolved if all files are opened, or rejected if there was an error. +**Returns**: Promise - Promise that is resolved if all files are opened, or rejected + if there was an error. | Param | Type | Description | | --- | --- | --- | -| files | Array.<string> | Array of files dropped on the application. | +| paths | Array.<string> | Array of file paths dropped on the application. | ## attachHandlers() -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. +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 diff --git a/docs/API-Reference/utils/DropdownEventHandler.md b/docs/API-Reference/utils/DropdownEventHandler.md index 0e634e2a44..b8b6375e99 100644 --- a/docs/API-Reference/utils/DropdownEventHandler.md +++ b/docs/API-Reference/utils/DropdownEventHandler.md @@ -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) ⇒ boolean - * [.closeCallback()](#DropdownEventHandler+open..closeCallback) * [.close()](#DropdownEventHandler+close) - * [._cleanup()](#DropdownEventHandler+_cleanup) - * [._tryToSelect(index, direction, [noWrap])](#DropdownEventHandler+_tryToSelect) - * [._itemsPerPage()](#DropdownEventHandler+_itemsPerPage) ⇒ number - * [._selectionHandler()](#DropdownEventHandler+_selectionHandler) - * [._clickHandler($item)](#DropdownEventHandler+_clickHandler) - * [._registerMouseEvents()](#DropdownEventHandler+_registerMouseEvents) * [.reRegisterMouseHandlers($list)](#DropdownEventHandler+reRegisterMouseHandlers) ### 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 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. +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 | @@ -41,81 +48,11 @@ Object to handle events for a dropdown list. DropdownEventHandler handles these Public open method **Kind**: instance method of [DropdownEventHandler](#DropdownEventHandler) - -* [.open()](#DropdownEventHandler+open) - * [._keydownHook(event)](#DropdownEventHandler+open.._keydownHook) ⇒ boolean - * [.closeCallback()](#DropdownEventHandler+open..closeCallback) - - - -#### open.\_keydownHook(event) ⇒ boolean -Convert keydown events into hint list navigation actions. - -**Kind**: inner method of [open](#DropdownEventHandler+open) -**Returns**: boolean - true if key was handled, otherwise false. - -| Param | Type | -| --- | --- | -| event | KeyboardEvent | - - - -#### open.closeCallback() -PopUpManager callback - -**Kind**: inner method of [open](#DropdownEventHandler+open) ### dropdownEventHandler.close() Public close method -**Kind**: instance method of [DropdownEventHandler](#DropdownEventHandler) - - -### dropdownEventHandler.\_cleanup() -Cleanup - -**Kind**: instance method of [DropdownEventHandler](#DropdownEventHandler) - - -### dropdownEventHandler.\_tryToSelect(index, direction, [noWrap]) -Try to select item at the given index. If it's disabled or a divider, keep trying by incrementing index by 'direction' each time (wrapping around if needed). - -**Kind**: instance method of [DropdownEventHandler](#DropdownEventHandler) - -| Param | Type | Description | -| --- | --- | --- | -| index | number | 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 | number | Either +1 or -1 | -| [noWrap] | boolean | Clip out of range index values instead of wrapping. Default false (wrap). | - - - -### dropdownEventHandler.\_itemsPerPage() ⇒ number -**Kind**: instance method of [DropdownEventHandler](#DropdownEventHandler) -**Returns**: number - The number of items per scroll page. - - -### dropdownEventHandler.\_selectionHandler() -Call selectionCallback with selected index - -**Kind**: instance method of [DropdownEventHandler](#DropdownEventHandler) - - -### dropdownEventHandler.\_clickHandler($item) -Call selectionCallback with selected item - -**Kind**: instance method of [DropdownEventHandler](#DropdownEventHandler) - -| Param | Type | -| --- | --- | -| $item | jQueryObject | - - - -### dropdownEventHandler.\_registerMouseEvents() -Register mouse event handlers - **Kind**: instance method of [DropdownEventHandler](#DropdownEventHandler) diff --git a/docs/API-Reference/utils/EventDispatcher.md b/docs/API-Reference/utils/EventDispatcher.md index db01c3b62e..2692eb1569 100644 --- a/docs/API-Reference/utils/EventDispatcher.md +++ b/docs/API-Reference/utils/EventDispatcher.md @@ -6,19 +6,83 @@ const EventDispatcher = brackets.getModule("utils/EventDispatcher") ## utils/EventDispatcher -Implements a jQuery-like event dispatch pattern for non-DOM objects (works in web workers and phoenix node as well): - Listeners are attached via on()/one() & detached via off() - Listeners can use namespaces for easy removal - Listeners can attach to multiple events at once via a space-separated list - Events are fired via trigger() - The same listener can be attached twice, and will be called twice; but off() will detach all duplicate copies at once ('duplicate' means '===' equality - see http://jsfiddle.net/bf4p29g5/1/) But it has some important differences from jQuery's non-DOM event mechanism: - More robust to listeners that throw exceptions (other listeners will still be called, and trigger() will still return control to its caller). - Events can be marked deprecated, causing on() to issue warnings - Easier to debug, since the dispatch code is much simpler - Faster, for the same reason - Uses less memory, since $(nonDOMObj).on() leaks memory in jQuery - API is simplified: - Event handlers do not have 'this' set to the event dispatcher object - Event object passed to handlers only has 'type' and 'target' fields - trigger() uses a simpler argument-list signature (like Promise APIs), rather than requiring an Array arg and ignoring additional args - trigger() does not support namespaces - For simplicity, on() does not accept a map of multiple events -> multiple handlers, nor a missing arg standing in for a bare 'return false' handler. For now, Brackets uses a jQuery patch to ensure $(obj).on() and obj.on() (etc.) are identical for any obj that has the EventDispatcher pattern. In the future, this may be deprecated. To add EventDispatcher methods to any object, call EventDispatcher.makeEventDispatcher(obj). ## Usage ### Importing from an extension +Implements a jQuery-like event dispatch pattern for non-DOM objects (works in web workers and phoenix node as well): + - Listeners are attached via on()/one() & detached via off() + - Listeners can use namespaces for easy removal + - Listeners can attach to multiple events at once via a space-separated list + - Events are fired via trigger() + - The same listener can be attached twice, and will be called twice; but off() will detach all + duplicate copies at once ('duplicate' means '===' equality - see http://jsfiddle.net/bf4p29g5/1/) + +But it has some important differences from jQuery's non-DOM event mechanism: + - More robust to listeners that throw exceptions (other listeners will still be called, and + trigger() will still return control to its caller). + - Events can be marked deprecated, causing on() to issue warnings + - Easier to debug, since the dispatch code is much simpler + - Faster, for the same reason + - Uses less memory, since $(nonDOMObj).on() leaks memory in jQuery + - API is simplified: + - Event handlers do not have 'this' set to the event dispatcher object + - Event object passed to handlers only has 'type' and 'target' fields + - trigger() uses a simpler argument-list signature (like Promise APIs), rather than requiring + an Array arg and ignoring additional args + - trigger() does not support namespaces + - For simplicity, on() does not accept a map of multiple events -> multiple handlers, nor a + missing arg standing in for a bare 'return false' handler. + +For now, Brackets uses a jQuery patch to ensure $(obj).on() and obj.on() (etc.) are identical +for any obj that has the EventDispatcher pattern. In the future, this may be deprecated. + +To add EventDispatcher methods to any object, call EventDispatcher.makeEventDispatcher(obj). + +## Usage +### Importing from an extension **Example** -```js const EventDispatcher = brackets.getModule("utils/EventDispatcher"); ``` ### Using the global object The EventDispatcher Object is available within the global context, be it phoenix or phoenix core web workers or node. +```js +const EventDispatcher = brackets.getModule("utils/EventDispatcher"); +``` +### Using the global object +The EventDispatcher Object is available within the global context, be it phoenix or phoenix core web workers or node. **Example** -```js window.EventDispatcher.makeEventDispatcher(exports); // within phoenix require module self.EventDispatcher.makeEventDispatcher(object); // within web worker global.EventDispatcher.makeEventDispatcher(exports); // within node module that has an export ``` If you wish to import event dispatcher to your custom web worker, use the following +```js +window.EventDispatcher.makeEventDispatcher(exports); // within phoenix require module +self.EventDispatcher.makeEventDispatcher(object); // within web worker +global.EventDispatcher.makeEventDispatcher(exports); // within node module that has an export +``` + +If you wish to import event dispatcher to your custom web worker, use the following **Example** -```js importScripts('/utils/EventDispatcher'); // this will add the global EventDispatcher to your web-worker. Note that the EventDispatcher in the web worker // and node is a separate domain and cannot raise or listen to events in phoenix/other workers. For triggering events // between different domains like between node and phcode, see `nodeConnector.triggerPeer` or // `WorkerComm.triggerPeer` API for communication between phcode and web workers. self.EventDispatcher.trigger("someEvent"); // within web worker ``` ### Sample Usage within extension +```js +importScripts('/utils/EventDispatcher'); +// this will add the global EventDispatcher to your web-worker. Note that the EventDispatcher in the web worker +// and node is a separate domain and cannot raise or listen to events in phoenix/other workers. For triggering events +// between different domains like between node and phcode, see `nodeConnector.triggerPeer` or +// `WorkerComm.triggerPeer` API for communication between phcode and web workers. +self.EventDispatcher.trigger("someEvent"); // within web worker +``` +### Sample Usage within extension **Example** -```js // in your extension js file. define (function (require, exports, module) { const EventDispatcher = brackets.getModule("utils/EventDispatcher"); EventDispatcher.makeEventDispatcher(exports); // This extension triggers some events let eventHandler = function (event, paramObject, paramVal) { console.log(event, paramObject, paramVal); }; exports.on("sampleEvent", eventHandler); // listen to our own event for demo exports.trigger("sampleEvent", { // trigger a sample event. This will activate the above listener 'on' function. param: 1, param2: "sample" }, "value"); // If needed, the event listener can be removed with `off`. But it is not a requirement at shutdown. exports.off("sampleEvent", eventHandler); } ``` +```js +// in your extension js file. +define (function (require, exports, module) { + const EventDispatcher = brackets.getModule("utils/EventDispatcher"); + EventDispatcher.makeEventDispatcher(exports); // This extension triggers some events + let eventHandler = function (event, paramObject, paramVal) { + console.log(event, paramObject, paramVal); + }; + exports.on("sampleEvent", eventHandler); // listen to our own event for demo + exports.trigger("sampleEvent", { // trigger a sample event. This will activate the above listener 'on' function. + param: 1, + param2: "sample" + }, "value"); + // If needed, the event listener can be removed with `off`. But it is not a requirement at shutdown. + exports.off("sampleEvent", eventHandler); +} +``` * [utils/EventDispatcher](#module_utils/EventDispatcher) - * [.splitNs(eventName)](#module_utils/EventDispatcher..splitNs) ⇒ Object + * [.splitNs(eventStr)](#module_utils/EventDispatcher..splitNs) ⇒ Object * [.setLeakThresholdForEvent(eventName, threshold)](#module_utils/EventDispatcher..setLeakThresholdForEvent) : function * [.on(events, fn)](#module_utils/EventDispatcher..on) : function * [.off(events, fn)](#module_utils/EventDispatcher..off) : function @@ -31,7 +95,7 @@ Implements a jQuery-like event dispatch pattern for non-DOM objects (works in we -### utils/EventDispatcher.splitNs(eventName) ⇒ Object +### utils/EventDispatcher.splitNs(eventStr) ⇒ Object Split "event.namespace" string into its two parts; both parts are optional. **Kind**: inner method of [utils/EventDispatcher](#module_utils/EventDispatcher) @@ -39,12 +103,14 @@ Split "event.namespace" string into its two parts; both parts are optional. | Param | Type | Description | | --- | --- | --- | -| eventName | string | Event name and/or trailing ".namespace" | +| eventStr | string | Event name and/or trailing ".namespace" | ### utils/EventDispatcher.setLeakThresholdForEvent(eventName, threshold) : function -By default, we consider any events having more than 15 listeners to be leaky. But sometimes there may be genuine use cases where an event can have a large number of listeners. For those events, it is recommended to increase the leaky warning threshold individually with this API. +By default, we consider any events having more than 15 listeners to be leaky. But sometimes there may be +genuine use cases where an event can have a large number of listeners. For those events, it is recommended +to increase the leaky warning threshold individually with this API. **Kind**: inner method of [utils/EventDispatcher](#module_utils/EventDispatcher) @@ -56,7 +122,9 @@ By default, we consider any events having more than 15 listeners to be leaky. Bu ### utils/EventDispatcher.on(events, fn) : function -Adds the given handler function to 'events': a space-separated list of one or more event names, each with an optional ".namespace" (used by off() - see below). If the handler is already listening to this event, a duplicate copy is added. +Adds the given handler function to 'events': a space-separated list of one or more event names, each +with an optional ".namespace" (used by off() - see below). If the handler is already listening to this +event, a duplicate copy is added. **Kind**: inner method of [utils/EventDispatcher](#module_utils/EventDispatcher) @@ -68,7 +136,10 @@ Adds the given handler function to 'events': a space-separated list of one or mo ### utils/EventDispatcher.off(events, fn) : function -Removes one or more handler functions based on the space-separated 'events' list. Each item in 'events' can be: bare event name, bare .namespace, or event.namespace pair. This yields a set of matching handlers. If 'fn' is omitted, all these handlers are removed. If 'fn' is provided, only handlers exactly equal to 'fn' are removed (there may still be >1, if duplicates were added). +Removes one or more handler functions based on the space-separated 'events' list. Each item in +'events' can be: bare event name, bare .namespace, or event.namespace pair. This yields a set of +matching handlers. If 'fn' is omitted, all these handlers are removed. If 'fn' is provided, +only handlers exactly equal to 'fn' are removed (there may still be >1, if duplicates were added). **Kind**: inner method of [utils/EventDispatcher](#module_utils/EventDispatcher) @@ -104,7 +175,8 @@ Invokes all handlers for the given event (in the order they were added). ### utils/EventDispatcher.makeEventDispatcher(obj) : function -Adds the EventDispatcher APIs to the given object: on(), one(), off(), and trigger(). May also be called on a prototype object - each instance will still behave independently. +Adds the EventDispatcher APIs to the given object: on(), one(), off(), and trigger(). May also be +called on a prototype object - each instance will still behave independently. **Kind**: inner method of [utils/EventDispatcher](#module_utils/EventDispatcher) @@ -115,7 +187,8 @@ Adds the EventDispatcher APIs to the given object: on(), one(), off(), and trigg ### utils/EventDispatcher.triggerWithArray(dispatcher, eventName, argsArray) : function -Utility for calling on() with an array of arguments to pass to event handlers (rather than a varargs list). makeEventDispatcher() must have previously been called on 'dispatcher'. +Utility for calling on() with an array of arguments to pass to event handlers (rather than a varargs +list). makeEventDispatcher() must have previously been called on 'dispatcher'. **Kind**: inner method of [utils/EventDispatcher](#module_utils/EventDispatcher) @@ -128,7 +201,14 @@ Utility for calling on() with an array of arguments to pass to event handlers (r ### utils/EventDispatcher.on\_duringInit(futureDispatcher, events, fn) : function -Utility for attaching an event handler to an object that has not YET had makeEventDispatcher() called on it, but will in the future. Once 'futureDispatcher' becomes a real event dispatcher, any handlers attached here will be retained. Useful with core modules that have circular dependencies (one module initially gets an empty copy of the other, with no on() API present yet). Unlike other strategies like waiting for htmlReady(), this helper guarantees you won't miss any future events, regardless of how soon the other module finishes init and starts calling trigger(). +Utility for attaching an event handler to an object that has not YET had makeEventDispatcher() called +on it, but will in the future. Once 'futureDispatcher' becomes a real event dispatcher, any handlers +attached here will be retained. + +Useful with core modules that have circular dependencies (one module initially gets an empty copy of the +other, with no on() API present yet). Unlike other strategies like waiting for htmlReady(), this helper +guarantees you won't miss any future events, regardless of how soon the other module finishes init and +starts calling trigger(). **Kind**: inner method of [utils/EventDispatcher](#module_utils/EventDispatcher) @@ -141,7 +221,10 @@ Utility for attaching an event handler to an object that has not YET had makeEve ### utils/EventDispatcher.markDeprecated(obj, eventName, [insteadStr]) : function -Mark a given event name as deprecated, such that on() will emit warnings when called with it. May be called before makeEventDispatcher(). May be called on a prototype where makeEventDispatcher() is called separately per instance (i.e. in the constructor). Should be called before clients have a chance to start calling on(). +Mark a given event name as deprecated, such that on() will emit warnings when called with it. +May be called before makeEventDispatcher(). May be called on a prototype where makeEventDispatcher() +is called separately per instance (i.e. in the constructor). Should be called before clients have +a chance to start calling on(). **Kind**: inner method of [utils/EventDispatcher](#module_utils/EventDispatcher) diff --git a/docs/API-Reference/utils/EventManager.md b/docs/API-Reference/utils/EventManager.md index 142a74ec28..5fbd96a628 100644 --- a/docs/API-Reference/utils/EventManager.md +++ b/docs/API-Reference/utils/EventManager.md @@ -6,22 +6,55 @@ const EventManager = brackets.getModule("utils/EventManager") ## utils/EventManager -The global EventManager can be used to register named EventDispatchers so that events can be triggered from anywhere without using require context. This should also be used to handle custom `window.onmessage` handlers. A global `window.EventManager` object is made available in phoenix that can be called anytime after AppStart. ## Usage For Eg. Let's say we have an extension `drawImage` installed that wants to expose custom functionality to phoenix. The Extension will first register named EventHandler like this: +The global EventManager can be used to register named EventDispatchers so that events +can be triggered from anywhere without using require context. This should also be used to handle custom +`window.onmessage` handlers. + +A global `window.EventManager` object is made available in phoenix that can be called anytime after AppStart. + +## Usage +For Eg. Let's say we have an extension `drawImage` installed that wants to expose custom functionality to phoenix. +The Extension will first register named EventHandler like this: **Example** -```js // in drawImage/someExtensionModule.js module within the extension, do the following: const EventDispatcher = brackets.getModule("utils/EventDispatcher"), EventManager = brackets.getModule("utils/EventManager"); EventDispatcher.makeEventDispatcher(exports); EventManager.registerEventHandler("drawImage-Handler", exports); ``` Once the event handler is registered, we can trigger events on the named handler anywhere in phoenix (inside or outside the extension) by using: +```js +// in drawImage/someExtensionModule.js module within the extension, do the following: +const EventDispatcher = brackets.getModule("utils/EventDispatcher"), +EventManager = brackets.getModule("utils/EventManager"); +EventDispatcher.makeEventDispatcher(exports); + +EventManager.registerEventHandler("drawImage-Handler", exports); +``` +Once the event handler is registered, we can trigger events on the named handler anywhere in phoenix +(inside or outside the extension) by using: **Example** -```js EventManager.triggerEvent("drawImage-Handler", "someEventName", "param1", "param2", ...); ``` +```js +EventManager.triggerEvent("drawImage-Handler", "someEventName", "param1", "param2", ...); +``` * [utils/EventManager](#module_utils/EventManager) * [.registerEventHandler(handlerName, eventDispatcher)](#module_utils/EventManager..registerEventHandler) ⇒ boolean * [.isExistsEventHandler(handlerName)](#module_utils/EventManager..isExistsEventHandler) ⇒ boolean * [.triggerEvent(handlerName, eventName, ...eventParams)](#module_utils/EventManager..triggerEvent) : function + * [.setTrustedOrigin(origin, isTrusted)](#module_utils/EventManager..setTrustedOrigin) ### utils/EventManager.registerEventHandler(handlerName, eventDispatcher) ⇒ boolean -Registers a named EventHandler. Event handlers are created using the call: `EventDispatcher.makeEventDispatcher(Command.prototype);` To register a close dialogue event handler in an extension: // in close-dialogue.js module winthin the extension, do the following: const EventDispatcher = brackets.getModule("utils/EventDispatcher"), EventDispatcher.makeEventDispatcher(exports); const EventManager = brackets.getModule("utils/EventManager"); // Note: for event handler names, please change the `extensionName` to your extension name // to prevent collisions. EventHandlers starting with `ph-` and `br-` are reserved as system handlers // and not available for use in extensions. EventManager.registerEventHandler("`extensionName`-closeDialogueHandler", exports); // Once the event handler is registered, see triggerEvent API on how to raise events +Registers a named EventHandler. Event handlers are created using the call: +`EventDispatcher.makeEventDispatcher(Command.prototype);` + +To register a close dialogue event handler in an extension: +// in close-dialogue.js module winthin the extension, do the following: +const EventDispatcher = brackets.getModule("utils/EventDispatcher"), +EventDispatcher.makeEventDispatcher(exports); +const EventManager = brackets.getModule("utils/EventManager"); + +// Note: for event handler names, please change the `extensionName` to your extension name +// to prevent collisions. EventHandlers starting with `ph-` and `br-` are reserved as system handlers +// and not available for use in extensions. +EventManager.registerEventHandler("`extensionName`-closeDialogueHandler", exports); +// Once the event handler is registered, see triggerEvent API on how to raise events **Kind**: inner method of [utils/EventManager](#module_utils/EventManager) @@ -44,7 +77,12 @@ Returns true is an EventHandler of the given name exists. ### utils/EventManager.triggerEvent(handlerName, eventName, ...eventParams) : function -Triggers an event on the named event handler. To trigger an event to the `closeDialogue` event handler registered above // anywhere in code, do the following: const EventManager = brackets.getModule("utils/EventManager"); EventManager.triggerEvent("closeDialogueHandler", "someEvent", "param1", "param2", ...); +Triggers an event on the named event handler. + +To trigger an event to the `closeDialogue` event handler registered above +// anywhere in code, do the following: +const EventManager = brackets.getModule("utils/EventManager"); +EventManager.triggerEvent("closeDialogueHandler", "someEvent", "param1", "param2", ...); **Kind**: inner method of [utils/EventManager](#module_utils/EventManager) @@ -54,14 +92,15 @@ Triggers an event on the named event handler. To trigger an event to the `close | eventName | | the event name as recognised by the handler. this is usually a string. | | ...eventParams | | Can be a comma seperated list of args or a single argument. | - + -## onmessage(event) -This function acts as a secure event handler for all 'message' events targeted at the window object. This is useful if you have to send/receive messaged from an embedded cross-domain iframe inside phoenix. https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage Instead of directly overriding window.onmessage, extensions or other elements that need to listen to these events should register their named eventHandler with `EventManager`. By default, only origins part of `window.Phoenix.TRUSTED_ORIGINS` are whitelisted. If your extension is bringing in a cross-origin ifrmame say [`http://mydomain.com`], you should add it to the whitelist by setting `window.Phoenix.TRUSTED_ORIGINS ["http://mydomain.com"] = true;` +### utils/EventManager.setTrustedOrigin(origin, isTrusted) +add or remove a domain, in the list of trusted origin -**Kind**: global function +**Kind**: inner method of [utils/EventManager](#module_utils/EventManager) | Param | Type | Description | | --- | --- | --- | -| event | MessageEvent | The 'message' event targeted at the window object. The event's 'data' property should have a 'handlerName' and `eventName` property that will be triggered in phcode. // We will try to communicate within an embedded iframe and an extension // In your extension in phoenix, register a handlerName to process a new kind of event. const EventDispatcher = brackets.getModule("utils/EventDispatcher"), EventDispatcher.makeEventDispatcher(exports); const EventManager = brackets.getModule("utils/EventManager"); // Note: for event handler names, please change the `extensionName` to your extension name // to prevent collisions. EventHandlers starting with `ph-` and `br-` are reserved as system handlers // and not available for use in extensions. window.Phoenix.TRUSTED_ORIGINS ["http://mydomain.com"] = true; ```js EventManager.registerEventHandler("`extensionName`-iframeMessageHandler", exports); exports.on("iframeHelloEvent", function(_ev, event){ console.log(event.data.message); }); ``` // Now from your iframe, send a message to the above event handler using: ```js window.parent.postMessage({ handlerName: "`extensionName`-iframeMessageHandler", eventName: "iframeHelloEvent", message: "hello world" }, '*'); ``` // `you should replace * with the trusted domains list in production for security.` See how this can be // done securely with this example: https://github.com/phcode-dev/phcode.live/blob/6d64386fbb9d671cdb64622bc48ffe5f71959bff/docs/virtual-server-loader.js#L43 // Abstract is that, pass in the parentOrigin as a query string parameter in iframe, and validate it against // a trusted domains list in your iframe. | +| origin | string | the origin to be added or removed | +| isTrusted | boolean | if `true` adds the origin to the list, else removes it. | diff --git a/docs/API-Reference/utils/ExtensionInterface.md b/docs/API-Reference/utils/ExtensionInterface.md index e982e9b28d..549320cf17 100644 --- a/docs/API-Reference/utils/ExtensionInterface.md +++ b/docs/API-Reference/utils/ExtensionInterface.md @@ -6,22 +6,58 @@ const ExtensionInterface = brackets.getModule("utils/ExtensionInterface") ## utils/ExtensionInterface -ExtensionInterface defines utility methods for communicating between extensions safely. A global `window.ExtensionInterface` object is made available in phoenix that can be called anytime after AppStart. ## Usage For Eg. You may have two extensions installed say `angular` extension which has to call functions made available by `angular-cli` Extension. For Making this possible, the `angular-cli` extension makes a named interface available with the ExtensionInterface module and `angular` extension can get hold of the interface as and when the extension gets loaded. +ExtensionInterface defines utility methods for communicating between extensions safely. +A global `window.ExtensionInterface` object is made available in phoenix that can be called anytime after AppStart. + +## Usage +For Eg. You may have two extensions installed say `angular` extension which has to call functions made available by +`angular-cli` Extension. + +For Making this possible, the `angular-cli` extension makes a named interface available with the ExtensionInterface +module and `angular` extension can get hold of the interface as and when the extension gets loaded. **Example** -```js // in angular-cli extension, make a file say cli-interface.js module within the extension, do the following: const ExtensionInterface = brackets.getModule("utils/ExtensionInterface"), // You can replace exports with any object you want to expose outside the extension really. ExtensionInterface.registerExtensionInterface("angularCli", exports); ``` Once the interface is registered, the angular extension can get hold of the interface with the following code (inside or outside the extension) by using: +```js +// in angular-cli extension, make a file say cli-interface.js module within the extension, do the following: +const ExtensionInterface = brackets.getModule("utils/ExtensionInterface"), +// You can replace exports with any object you want to expose outside the extension really. +ExtensionInterface.registerExtensionInterface("angularCli", exports); +``` +Once the interface is registered, the angular extension can get hold of the interface with the following code +(inside or outside the extension) by using: **Example** -```js let angularCli; ExtensionInterface.waitAndGetExtensionInterface("angularCli").then(interfaceObj=> angularCli = interfaceObj); if(angularCli){ // check if angular cli is avilable angularCli.callSomeFunction(); } ``` **Note** that the `angularCli` interface is async populated as and when the cli extension is loaded and the interface made available. **NBB:** Do Not use `await waitAndGetExtensionInterface` on tol level require as the module loading might fail. +```js +let angularCli; +ExtensionInterface.waitAndGetExtensionInterface("angularCli").then(interfaceObj=> angularCli = interfaceObj); +if(angularCli){ // check if angular cli is avilable +angularCli.callSomeFunction(); +} +``` + +**Note** that the `angularCli` interface is async populated as and when the cli extension is loaded and the +interface made available. + +**NBB:** Do Not use `await waitAndGetExtensionInterface` on tol level require as the module loading might fail. * [utils/ExtensionInterface](#module_utils/ExtensionInterface) + * [.EVENT_EXTENSION_INTERFACE_REGISTERED](#module_utils/ExtensionInterface..EVENT_EXTENSION_INTERFACE_REGISTERED) : string * [.registerExtensionInterface(extensionInterfaceName, interfaceObject)](#module_utils/ExtensionInterface..registerExtensionInterface) : function * [.isExistsExtensionInterface(extensionInterfaceName)](#module_utils/ExtensionInterface..isExistsExtensionInterface) ⇒ boolean * [.waitAndGetExtensionInterface(extensionInterfaceName)](#module_utils/ExtensionInterface..waitAndGetExtensionInterface) ⇒ Promise + + +### utils/ExtensionInterface.EVENT\_EXTENSION\_INTERFACE\_REGISTERED : string +Extension interface registered event + +**Kind**: inner constant of [utils/ExtensionInterface](#module_utils/ExtensionInterface) ### utils/ExtensionInterface.registerExtensionInterface(extensionInterfaceName, interfaceObject) : function -Registers a named extension interface. Will overwrite if an interface of the same name is already present. To register an interface `angularCli` ExtensionInterface.registerExtensionInterface("angularCli", exports); +Registers a named extension interface. Will overwrite if an interface of the same name is already present. + +To register an interface `angularCli` +ExtensionInterface.registerExtensionInterface("angularCli", exports); **Kind**: inner method of [utils/ExtensionInterface](#module_utils/ExtensionInterface) @@ -44,7 +80,17 @@ Returns true is an interface of the given name exists. ### utils/ExtensionInterface.waitAndGetExtensionInterface(extensionInterfaceName) ⇒ Promise -Returns a promise that gets resolved only when an ExtensionInterface of the given name is registered. Use this getter to get hold of extensions interface predictably. To get a registered interface `angularCli` ```js let angularCli; ExtensionInterface.waitAndGetExtensionInterface("angularCli").then(interfaceObj=> angularCli = interfaceObj); if(angularCli){ // check if angular cli is avilable angularCli.callSomeFunction(); } ``` +Returns a promise that gets resolved only when an ExtensionInterface of the given name is registered. Use this +getter to get hold of extensions interface predictably. + +To get a registered interface `angularCli` +```js +let angularCli; +ExtensionInterface.waitAndGetExtensionInterface("angularCli").then(interfaceObj=> angularCli = interfaceObj); +if(angularCli){ // check if angular cli is avilable +angularCli.callSomeFunction(); +} +``` **Kind**: inner method of [utils/ExtensionInterface](#module_utils/ExtensionInterface) diff --git a/docs/API-Reference/utils/ExtensionLoader.md b/docs/API-Reference/utils/ExtensionLoader.md index 0ff291f3b4..c514f2a01e 100644 --- a/docs/API-Reference/utils/ExtensionLoader.md +++ b/docs/API-Reference/utils/ExtensionLoader.md @@ -3,94 +3,71 @@ const ExtensionLoader = brackets.getModule("utils/ExtensionLoader") ``` - + -## contexts : Object.<string, Object> -Stores require.js contexts of extensions +## EVENT\_EXTENSION\_LOADED : string +Extension loaded event -**Kind**: global variable - +**Kind**: global constant + -## DEFAULT\_EXTENSIONS\_PATH\_BASE -Returns the path to the default extensions directory relative to Phoenix base URL +## EVENT\_EXTENSION\_DISABLED : string +Extension disabled event **Kind**: global constant - + -## \_getExtensionPath() -Returns the full path to the development extensions directory. +## EVENT\_EXTENSION\_LOAD\_FAILED : string +Extension load failed event -**Kind**: global function - +**Kind**: global constant + -## getDevExtensionPath() -Returns the full path to the development extensions directory. +## getDefaultExtensionPath() ⇒ string +Responsible to get the default extension path **Kind**: global function ## getUserExtensionPath() -Returns the full path of the default user extensions directory. This is in the users application support directory, which is typically /Users/"user"/Application Support/Brackets/extensions/user on the mac, and C:\Users\"user"\AppData\Roaming\Brackets\extensions\user on windows. +Returns the full path of the default user extensions directory. This is in the users +application support directory, which is typically +/Users/"user"/Application Support/Brackets/extensions/user on the mac, and +C:\Users\"user"\AppData\Roaming\Brackets\extensions\user on windows. **Kind**: global function -## getRequireContextForExtension(name,) ⇒ Object +## getRequireContextForExtension(name) ⇒ Object Returns the require.js require context used to load an extension **Kind**: global function -**Returns**: Object - A require.js require object used to load the extension, or undefined if there is no require object with that name - -| Param | Type | Description | -| --- | --- | --- | -| name, | string | used to identify the extension | - - - -## loadExtensionModule(name,, config, entryPoint, metadata) ⇒ $.Promise -Loads the extension module that lives at baseUrl into its own Require.js context - -**Kind**: global function -**Returns**: $.Promise - A promise object that is resolved when the extension is loaded, or rejected if the extension fails to load or throws an exception immediately when loaded. (Note: if extension contains a JS syntax error, promise is resolved not rejected). +**Returns**: Object - A require.js require object used to load the extension, or undefined if +there is no require object with that name | Param | Type | Description | | --- | --- | --- | -| name, | string | used to identify the extension | -| config | Object | object with baseUrl property containing absolute path of extension | -| entryPoint | string | name of the main js file to load | -| metadata | Object | | +| name | string | used to identify the extension | -## loadExtension(name,, config, entryPoint,) ⇒ $.Promise +## loadExtension(name, config, entryPoint) ⇒ $.Promise Loads the extension that lives at baseUrl into its own Require.js context **Kind**: global function -**Returns**: $.Promise - A promise object that is resolved when the extension is loaded, or rejected if the extension fails to load or throws an exception immediately when loaded. (Note: if extension contains a JS syntax error, promise is resolved not rejected). +**Returns**: $.Promise - A promise object that is resolved when the extension is loaded, or rejected + if the extension fails to load or throws an exception immediately when loaded. + (Note: if extension contains a JS syntax error, promise is resolved not rejected). | Param | Type | Description | | --- | --- | --- | -| name, | string | used to identify the extension | +| name | string | used to identify the extension | | config | Object | object with baseUrl property containing absolute path of extension | -| entryPoint, | string | name of the main js file to load | - - - -## \_testExtensionByURL(name,, config, entryPoint,) ⇒ $.Promise -Runs unit tests for the extension that lives at baseUrl into its own Require.js context - -**Kind**: global function -**Returns**: $.Promise - A promise object that is resolved when all extensions complete loading. - -| Param | Type | Description | -| --- | --- | --- | -| name, | string | used to identify the extension | -| config | Object | object with baseUrl property containing absolute path of extension | -| entryPoint, | string | name of the main js file to load | +| entryPoint | string | name of the main js file to load | -## testExtension(name,, config, entryPoint,) ⇒ $.Promise +## testExtension(name, config, entryPoint) ⇒ $.Promise Runs unit tests for the extension that lives at baseUrl into its own Require.js context **Kind**: global function @@ -98,9 +75,9 @@ Runs unit tests for the extension that lives at baseUrl into its own Require.js | Param | Type | Description | | --- | --- | --- | -| name, | string | used to identify the extension | +| name | string | used to identify the extension | | config | Object | object with baseUrl property containing absolute path of extension | -| entryPoint, | string | name of the main js file to load | +| entryPoint | string | name of the main js file to load | @@ -111,7 +88,7 @@ Loads All brackets default extensions from brackets base https URL. **Returns**: $.Promise - A promise object that is resolved when all extensions complete loading. -## loadAllExtensionsInNativeDirectory(directory,) ⇒ $.Promise +## loadAllExtensionsInNativeDirectory(directory) ⇒ $.Promise Loads the extension that lives at baseUrl into its own Require.js context **Kind**: global function @@ -119,7 +96,7 @@ Loads the extension that lives at baseUrl into its own Require.js context | Param | Type | Description | | --- | --- | --- | -| directory, | string | an absolute native path that contains a directory of extensions. each subdirectory is interpreted as an independent extension | +| directory | string | an absolute native path that contains a directory of extensions. each subdirectory is interpreted as an independent extension | @@ -134,7 +111,7 @@ Loads a given extension at the path from virtual fs. Used by `debug menu> load p -## testAllExtensionsInNativeDirectory(directory,) ⇒ $.Promise +## testAllExtensionsInNativeDirectory(directory) ⇒ $.Promise Runs unit test for the extension that lives at baseUrl into its own Require.js context **Kind**: global function @@ -142,7 +119,7 @@ Runs unit test for the extension that lives at baseUrl into its own Require.js c | Param | Type | Description | | --- | --- | --- | -| directory, | string | an absolute native path that contains a directory of extensions. each subdirectory is interpreted as an independent extension | +| directory | string | an absolute native path that contains a directory of extensions. each subdirectory is interpreted as an independent extension | @@ -151,6 +128,17 @@ Runs unit test for the extension that lives at baseUrl into its own Require.js c **Kind**: global function **Returns**: $.Promise - A promise object that is resolved when all extensions complete loading. + + +## getSourcePathForExtension(extensionPath) ⇒ string +To get the source path for extension + +**Kind**: global function + +| Param | +| --- | +| extensionPath | + ## init(A) ⇒ $.Promise diff --git a/docs/API-Reference/utils/ExtensionUtils.md b/docs/API-Reference/utils/ExtensionUtils.md index 798a132e01..f6c0b1d1cc 100644 --- a/docs/API-Reference/utils/ExtensionUtils.md +++ b/docs/API-Reference/utils/ExtensionUtils.md @@ -34,21 +34,6 @@ Appends a "link" tag to the document's head. | url | string | URL to a style sheet | | [deferred] | $.Deferred | Optionally check for load and error events | - - -## isAbsolutePathOrUrl(pathOrUrl) ⇒ boolean -getModuleUrl returns different urls for win platform -so that's why we need a different check here - -**Kind**: global function -**Returns**: boolean - returns true if pathOrUrl is absolute url on win platform - or when it's absolute path on other platforms -**See**: #getModuleUrl - -| Param | Type | Description | -| --- | --- | --- | -| pathOrUrl | string | that should be checked if it's absolute | - ## parseLessCode(code, url) ⇒ $.Promise @@ -120,24 +105,9 @@ Loads a style sheet (CSS or LESS) relative to the extension module. | module | module | Module provided by RequireJS | | path | string | Relative path from the extension folder to a CSS or LESS file | - - -## \_loadExtensionMetadata(baseExtensionUrl, extensionName) ⇒ $.Promise -Loads the package.json file in the given extension folder as well as any additional -metadata. - -**Kind**: global function -**Returns**: $.Promise - A promise object that is resolved with the parsed contents of the package.json file, - or rejected if there is no package.json with the boolean indicating whether .disabled file exists. - -| Param | Type | Description | -| --- | --- | --- | -| baseExtensionUrl | string | The extension folder. | -| extensionName | string | optional extension name | - -## loadMetadata(metadataURL) ⇒ $.Promise +## loadMetadata(metadataURL, extensionName) ⇒ $.Promise Loads the package.json file in the given extension folder as well as any additional metadata for default extensions in the source directory. @@ -152,4 +122,5 @@ disabled might be set. | Param | Type | Description | | --- | --- | --- | | metadataURL | string | The extension folder/base url for default extensions. | +| extensionName | string | name of the extension | diff --git a/docs/API-Reference/utils/FeatureGate.md b/docs/API-Reference/utils/FeatureGate.md index b1fe5f97a8..0717e90e35 100644 --- a/docs/API-Reference/utils/FeatureGate.md +++ b/docs/API-Reference/utils/FeatureGate.md @@ -6,23 +6,59 @@ const FeatureGate = brackets.getModule("utils/FeatureGate") ## utils/FeatureGate -FeatureGate defines util methods for enabling or disabling features in development based on a flag in local storage. A global `window.FeatureGate` object is made available in phoenix that can be called anytime after AppStart. ## Usage For Eg. You may have an extensions in development that colors phoenix in red. But you are working on a new feature that makes other colors available, but not yet ready for use. So put the extension behind a named feature gate so that only people who want to test the extension will be able to use it. ### creating a feature gate +FeatureGate defines util methods for enabling or disabling features in development based on a flag in local storage. +A global `window.FeatureGate` object is made available in phoenix that can be called anytime after AppStart. + +## Usage +For Eg. You may have an extensions in development that colors phoenix in red. But you are working on a new feature +that makes other colors available, but not yet ready for use. So put the extension behind a named feature gate +so that only people who want to test the extension will be able to use it. + +### creating a feature gate **Example** -```js // within extensions const FeatureGate = brackets.getModule("utils/FeatureGate"); // replace with `require` for core modules. const FEATURE_NEW_COLORS = 'myExtension.newColors'; FeatureGate.registerFeatureGate(FEATURE_NEW_COLORS, false); // false is the default value ``` ### checking if a feature is gated Once the feature is registered, use the below code to check if the feature can be safely enabled. For Eg., if you want to enable fancy colors based on the example above: +```js +// within extensions +const FeatureGate = brackets.getModule("utils/FeatureGate"); // replace with `require` for core modules. +const FEATURE_NEW_COLORS = 'myExtension.newColors'; +FeatureGate.registerFeatureGate(FEATURE_NEW_COLORS, false); // false is the default value +``` + +### checking if a feature is gated +Once the feature is registered, use the below code to check if the feature can be safely enabled. For Eg., if +you want to enable fancy colors based on the example above: **Example** -```js if(FeatureGate.isFeatureEnabled(FEATURE_NEW_COLORS)){ // do fancy colors here } ``` ### Enabling features for testing 1. Open developer tools > local storage 2. Add a new key with the key you have specified for the feature gate. In the above Eg., the key is `myExtension.newColors` 3. set the value in local storage to `enabled` to enable the feature or anything else to disable. +```js +if(FeatureGate.isFeatureEnabled(FEATURE_NEW_COLORS)){ + // do fancy colors here +} +``` +### Enabling features for testing +1. Open developer tools > local storage +2. Add a new key with the key you have specified for the feature gate. + In the above Eg., the key is `myExtension.newColors` +3. set the value in local storage to `enabled` to enable the feature or anything else to disable. * [utils/FeatureGate](#module_utils/FeatureGate) + * [.FEATURE_REGISTERED](#module_utils/FeatureGate..FEATURE_REGISTERED) : string * [.registerFeatureGate(featureName, enabledDefault)](#module_utils/FeatureGate..registerFeatureGate) : function * [.getAllRegisteredFeatures()](#module_utils/FeatureGate..getAllRegisteredFeatures) ⇒ Array.<string> * [.isFeatureEnabled(featureName)](#module_utils/FeatureGate..isFeatureEnabled) ⇒ boolean * [.setFeatureEnabled(featureName, isEnabled)](#module_utils/FeatureGate..setFeatureEnabled) + + +### utils/FeatureGate.FEATURE\_REGISTERED : string +Feature gate registered + +**Kind**: inner constant of [utils/FeatureGate](#module_utils/FeatureGate) ### utils/FeatureGate.registerFeatureGate(featureName, enabledDefault) : function -Registers a named feature with the default enabled state. To register a feature gate with name `myExtension.newColors` const FEATURE_NEW_COLORS = 'myExtension.newColors'; FeatureGate.registerFeatureGate(FEATURE_NEW_COLORS, false); // false is the default value here +Registers a named feature with the default enabled state. +To register a feature gate with name `myExtension.newColors` +const FEATURE_NEW_COLORS = 'myExtension.newColors'; +FeatureGate.registerFeatureGate(FEATURE_NEW_COLORS, false); // false is the default value here **Kind**: inner method of [utils/FeatureGate](#module_utils/FeatureGate) @@ -41,7 +77,12 @@ Returns an array of all named registered feature gates. ### utils/FeatureGate.isFeatureEnabled(featureName) ⇒ boolean -Returns true is an featureGate is enabled either by default or overridden by the user using local storage. To check if the feature `myExtension.newColors` is enabled const FEATURE_NEW_COLORS = 'myExtension.newColors'; if(FeatureGate.isFeatureEnabled(FEATURE_NEW_COLORS)){ // do fancy colors here } +Returns true is an featureGate is enabled either by default or overridden by the user using local storage. +To check if the feature `myExtension.newColors` is enabled +const FEATURE_NEW_COLORS = 'myExtension.newColors'; +if(FeatureGate.isFeatureEnabled(FEATURE_NEW_COLORS)){ + // do fancy colors here +} **Kind**: inner method of [utils/FeatureGate](#module_utils/FeatureGate) diff --git a/docs/API-Reference/utils/Global.md b/docs/API-Reference/utils/Global.md deleted file mode 100644 index 32c510a83a..0000000000 --- a/docs/API-Reference/utils/Global.md +++ /dev/null @@ -1,11 +0,0 @@ -### Import : -```js -const Global = brackets.getModule("utils/Global") -``` - - - -## configJSON -Initializes the global "brackets" variable and it's properties. Modules should not access the global.brackets object until either (a) the module requires this module, i.e. require("utils/Global") or (b) the module receives a "appReady" callback from the utils/AppReady module. - -**Kind**: global variable diff --git a/docs/API-Reference/utils/KeyEvent.md b/docs/API-Reference/utils/KeyEvent.md new file mode 100644 index 0000000000..7a7cca4a6c --- /dev/null +++ b/docs/API-Reference/utils/KeyEvent.md @@ -0,0 +1,5 @@ +### Import : +```js +const KeyEvent = brackets.getModule("utils/KeyEvent") +``` + diff --git a/docs/API-Reference/utils/NativeApp.md b/docs/API-Reference/utils/NativeApp.md new file mode 100644 index 0000000000..cbaeca5081 --- /dev/null +++ b/docs/API-Reference/utils/NativeApp.md @@ -0,0 +1,57 @@ +### Import : +```js +const NativeApp = brackets.getModule("utils/NativeApp") +``` + + + +## Async +Virtualized NativeApp apis that works cross-platform, and in the browser. + +**Kind**: global variable + + +## openLiveBrowser(url, [enableRemoteDebugging]) ⇒ $.Promise +openLiveBrowser +Open the given URL in the user's system browser, optionally enabling debugging. + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| url | string | The URL to open. | +| [enableRemoteDebugging] | boolean | Whether to turn on remote debugging. Default false. | + + + +## closeLiveBrowser() ⇒ $.Promise +closeLiveBrowser + +**Kind**: global function + + +## closeAllLiveBrowsers() ⇒ $.Promise +closeAllLiveBrowsers +Closes all the browsers that were tracked on open + +TODO: does not seem to work on Windows + +**Kind**: global function + + +## openURLInDefaultBrowser(url, tabIdentifier) +Opens a URL in the system default browser. + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| url | string | | +| tabIdentifier | string | An optional tab identifier can be set to group the tabs. Maps to target option in browser. Doesn't do anything in tauri. | + + + +## getApplicationSupportDirectory() +Gets the path to the application's support directory + +**Kind**: global function diff --git a/docs/API-Reference/utils/NodeConnection.md b/docs/API-Reference/utils/NodeConnection.md deleted file mode 100644 index 8aa10c13c9..0000000000 --- a/docs/API-Reference/utils/NodeConnection.md +++ /dev/null @@ -1,91 +0,0 @@ -### Import : -```js -const NodeConnection = brackets.getModule("utils/NodeConnection") -``` - - - -## NodeConnection -**Kind**: global class - -* [NodeConnection](#NodeConnection) - * [new NodeConnection()](#new_NodeConnection_new) - * [.domains](#NodeConnection+domains) : Object - * [.connect(autoReconnect)](#NodeConnection+connect) ⇒ jQuery.Promise - * [.connected()](#NodeConnection+connected) ⇒ boolean - * [.disconnect()](#NodeConnection+disconnect) - * [.loadDomains(List, autoReload)](#NodeConnection+loadDomains) ⇒ jQuery.Promise - - - -### new NodeConnection() -Provides an interface for interacting with the node server. - - - -### nodeConnection.domains : Object -Exposes the domains registered with the server. This object willhave a property for each registered domain. Each of those propertieswill be an object containing properties for all the commands in thatdomain. So, myConnection.base.enableDebugger would point to the functionto call to enable the debugger.This object is automatically replaced every time the API changes (basedon the base:newDomains event from the server). Therefore, code thatuses this object should not keep their own pointer to the domain property. - -**Kind**: instance property of [NodeConnection](#NodeConnection) - - -### nodeConnection.connect(autoReconnect) ⇒ jQuery.Promise -Connect to the node server. After connecting, the NodeConnection object will trigger a "close" event when the underlying socket is closed. If the connection is set to autoReconnect, then the event will also include a jQuery promise for the connection. - -**Kind**: instance method of [NodeConnection](#NodeConnection) -**Returns**: jQuery.Promise - Promise that resolves/rejects when the connection succeeds/fails - -| Param | Type | Description | -| --- | --- | --- | -| autoReconnect | boolean | Whether to automatically try to reconnect to the server if the connection succeeds and then later disconnects. Note if this connection fails initially, the autoReconnect flag is set to false. Future calls to connect() can reset it to true | - - - -### nodeConnection.connected() ⇒ boolean -Determines whether the NodeConnection is currently connected - -**Kind**: instance method of [NodeConnection](#NodeConnection) -**Returns**: boolean - Whether the NodeConnection is connected. - - -### nodeConnection.disconnect() -Explicitly disconnects from the server. Note that even if autoReconnect was set to true at connection time, the connection will not reconnect after this call. Reconnection can be manually done by calling connect() again. - -**Kind**: instance method of [NodeConnection](#NodeConnection) - - -### nodeConnection.loadDomains(List, autoReload) ⇒ jQuery.Promise -Load domains into the server by path - -**Kind**: instance method of [NodeConnection](#NodeConnection) -**Returns**: jQuery.Promise - Promise that resolves after the load has succeeded and the new API is availale at NodeConnection.domains, or that rejects on failure. - -| Param | Type | Description | -| --- | --- | --- | -| List | Array.<string> | of absolute paths to load | -| autoReload | boolean | Whether to auto-reload the domains if the server fails and restarts. Note that the reload is initiated by the client, so it will only happen after the client reconnects. | - - - -## CONNECTION\_ATTEMPTS : number -Connection attempts to make before failing - -**Kind**: global variable - - -## CONNECTION\_TIMEOUT : number -Milliseconds to wait before a particular connection attempt is considered failed. NOTE: It's okay for the connection timeout to be long because the expected behavior of WebSockets is to send a "close" event as soon as they realize they can't connect. So, we should rarely hit the connection timeout even if we try to connect to a port that isn't open. - -**Kind**: global variable - - -## RETRY\_DELAY : number -Milliseconds to wait before retrying connecting - -**Kind**: global variable - - -## MAX\_COUNTER\_VALUE : number -Maximum value of the command ID counter - -**Kind**: global variable diff --git a/docs/API-Reference/utils/NodeUtils.md b/docs/API-Reference/utils/NodeUtils.md new file mode 100644 index 0000000000..c23cebc8ef --- /dev/null +++ b/docs/API-Reference/utils/NodeUtils.md @@ -0,0 +1,84 @@ +### Import : +```js +const NodeUtils = brackets.getModule("utils/NodeUtils") +``` + + + +## isNodeReady ⇒ boolean +checks if Node connector is ready + +**Kind**: global variable +**Returns**: boolean - returns true if it's ready, otherwise false + + +## Strings +Generic node util APIs connector. see `src-node/utils.js` for node peer + +**Kind**: global constant + + +## fetchURLText(url, encoding) ⇒ Promise.<string> +Fetches text content from a URL +This is only available in the native app + +**Kind**: global function + +| Param | Type | +| --- | --- | +| url | string | +| encoding | string | + + + +## getPhoenixBinaryVersion() ⇒ Promise.<string> +Gets the version of the Phoenix binary +This is only available in the native app + +**Kind**: global function + + +## getLinuxOSFlavorName() ⇒ Promise.<(string\|null)> +Retrieves the Linux OS flavor name +This is only available in the native app on Linux + +**Kind**: global function + + +## openUrlInBrowser(url, browserName) +Opens a URL in the default browser. +This is only available in the native app. + +**Kind**: global function + +| Param | Type | +| --- | --- | +| url | string | +| browserName | string | + + + +## getEnvironmentVariable(varName) ⇒ Promise.<string> +Gets an environment variable's value +This is only available in the native app + +**Kind**: global function + +| Param | Type | +| --- | --- | +| varName | string | + + + +## ESLintFile(text, fullFilePath, projectFullPath) +Runs ESLint on a file +This is only available in the native app + +**Kind**: global function + +| Param | Type | +| --- | --- | +| text | string | +| fullFilePath | string | +| projectFullPath | string | + diff --git a/docs/API-Reference/utils/PerfUtils.md b/docs/API-Reference/utils/PerfUtils.md index 9dafd58cbd..edb5e49037 100644 --- a/docs/API-Reference/utils/PerfUtils.md +++ b/docs/API-Reference/utils/PerfUtils.md @@ -8,35 +8,12 @@ const PerfUtils = brackets.getModule("utils/PerfUtils") ## \_ This is a collection of utility functions for gathering performance data. -**Kind**: global variable - - -## enabled : boolean -Flag to enable/disable performance data gathering. Default is true (enabled) - -**Kind**: global variable - - -## perfData -Performance data is stored in this hash object. The key is the name of the test (passed to markStart/addMeasurement), and the value is the time, in milliseconds, that it took to run the test. If multiple runs of the same test are made, the value is an Array with each run stored as an entry in the Array. - -**Kind**: global variable - - -## activeTests -Active tests. This is a hash of all tests that have had markStart() called, but have not yet had addMeasurement() called. - -**Kind**: global variable - - -## updatableTests -Updatable tests. This is a hash of all tests that have had markStart() called, and have had updateMeasurement() called. Caller must explicitly remove tests from this list using finalizeMeasurement() - **Kind**: global variable ## createPerfMeasurement(id, name) -Create a new PerfMeasurement key. Adds itself to the module export. Can be accessed on the module, e.g. PerfUtils.MY_PERF_KEY. +Create a new PerfMeasurement key. Adds itself to the module export. +Can be accessed on the module, e.g. PerfUtils.MY_PERF_KEY. **Kind**: global function @@ -48,7 +25,15 @@ Create a new PerfMeasurement key. Adds itself to the module export. Can be acces ## markStart(name) ⇒ Object \| Array.<Object> -Start a new named timer. The name should be as descriptive as possible, since this name will appear as an entry in the performance report. For example: "Open file: /Users/brackets/src/ProjectManager.js" Multiple timers can be opened simultaneously. Returns an opaque set of timer ids which can be stored and used for calling addMeasurement(). Since name is often creating via concatenating strings this return value allows clients to construct the name once. +Start a new named timer. The name should be as descriptive as possible, since +this name will appear as an entry in the performance report. +For example: "Open file: /Users/brackets/src/ProjectManager.js" + +Multiple timers can be opened simultaneously. + +Returns an opaque set of timer ids which can be stored and used for calling +addMeasurement(). Since name is often creating via concatenating strings this +return value allows clients to construct the name once. **Kind**: global function **Returns**: Object \| Array.<Object> - Opaque timer id or array of timer ids. @@ -60,7 +45,13 @@ Start a new named timer. The name should be as descriptive as possible, since th ## addMeasurement(id) -Stop a timer and add its measurements to the performance data. Multiple measurements can be stored for any given name. If there are multiple values for a name, they are stored in an Array. If markStart() was not called for the specified timer, the measured time is relative to app startup. +Stop a timer and add its measurements to the performance data. + +Multiple measurements can be stored for any given name. If there are +multiple values for a name, they are stored in an Array. + +If markStart() was not called for the specified timer, the +measured time is relative to app startup. **Kind**: global function @@ -71,7 +62,21 @@ Stop a timer and add its measurements to the performance data. Multiple measure ## updateMeasurement(id) -This function is similar to addMeasurement(), but it allows timing the *last* event, when you don't know which event will be the last one. Tests that are in the activeTests list, have not yet been added, so add measurements to the performance data, and move test to updatableTests list. A test is moved to the updatable list so that it no longer passes isActive(). Tests that are already in the updatableTests list are updated. Caller must explicitly remove test from the updatableTests list using finalizeMeasurement(). If markStart() was not called for the specified timer, there is no way to determine if this is the first or subsequent call, so the measurement is not updatable, and it is handled in addMeasurement(). +This function is similar to addMeasurement(), but it allows timing the +*last* event, when you don't know which event will be the last one. + +Tests that are in the activeTests list, have not yet been added, so add +measurements to the performance data, and move test to updatableTests list. +A test is moved to the updatable list so that it no longer passes isActive(). + +Tests that are already in the updatableTests list are updated. + +Caller must explicitly remove test from the updatableTests list using +finalizeMeasurement(). + +If markStart() was not called for the specified timer, there is no way to +determine if this is the first or subsequent call, so the measurement is +not updatable, and it is handled in addMeasurement(). **Kind**: global function @@ -82,7 +87,10 @@ This function is similar to addMeasurement(), but it allows timing the *last* ev ## finalizeMeasurement(id) -Remove timer from lists so next action starts a new measurement updateMeasurement may not have been called, so timer may be in either or neither list, but should never be in both. +Remove timer from lists so next action starts a new measurement + +updateMeasurement may not have been called, so timer may be +in either or neither list, but should never be in both. **Kind**: global function @@ -93,7 +101,9 @@ Remove timer from lists so next action starts a new measurement updateMeasureme ## isActive(id) ⇒ boolean -Returns whether a timer is active or not, where "active" means that timer has been started with addMark(), but has not been added to perfdata with addMeasurement(). +Returns whether a timer is active or not, where "active" means that +timer has been started with addMark(), but has not been added to perfdata +with addMeasurement(). **Kind**: global function **Returns**: boolean - Whether a timer is active or not. @@ -102,19 +112,6 @@ Returns whether a timer is active or not, where "active" means that timer has be | --- | --- | --- | | id | Object | Timer id. | - - -## getValueAsString(entry, aggregateStats) ⇒ String -return single value, or comma separated values for an array or return aggregated values with "min value, average, max value, standard deviation" - -**Kind**: global function -**Returns**: String - a single value, or comma separated values in an array or "min(avg)max[standard deviation]" if aggregateStats is set - -| Param | Type | Description | -| --- | --- | --- | -| entry | Array | An array or a single value | -| aggregateStats | Boolean | If set, the returned value will be aggregated in the form - "min(avg)max[standard deviation]" | - ## getDelimitedPerfData() ⇒ string @@ -130,7 +127,7 @@ Returns the measured value for the given measurement name. | Param | Type | Description | | --- | --- | --- | -| id | Object | The measurement to retreive. | +| id | Object | The measurement to retrieve. | @@ -139,6 +136,17 @@ Returns the Performance metrics to be logged for health report **Kind**: global function **Returns**: Object - An object with the health data logs to be sent + + +## searchData(regExp) ⇒ Array +To search data given the regular expression + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| regExp | RegExp | the regular expression | + ## clear() diff --git a/docs/API-Reference/utils/Resizer.md b/docs/API-Reference/utils/Resizer.md index 9fbe9b7e0b..1f919125c6 100644 --- a/docs/API-Reference/utils/Resizer.md +++ b/docs/API-Reference/utils/Resizer.md @@ -5,10 +5,76 @@ const Resizer = brackets.getModule("utils/Resizer") -## DIRECTION\_VERTICAL -Resizer is a Module utility to inject resizing capabilities to any element inside Brackets. On initialization, Resizer discovers all nodes tagged as "vert-resizable" and "horz-resizable" to add the resizer handler. Additionally, "top-resizer", "bottom-resizer", "left-resizer" and "right-resizer" classes control the position of the resizer on the element. An element can be made resizable at any time using the `makeResizable()` API. Panel sizes are saved via preferences and restored when the DOM node becomes resizable again in a subsequent launch. The resizable elements trigger a panelResizeStart, panelResizeUpdate and panelResizeEnd event that can be used to create performance optimizations (such as hiding/showing elements while resizing), custom layout logic, etc. See makeResizable() for details on the events. A resizable element can be collapsed/expanded using the `show`, `hide` and `toggle` APIs or via user action. This triggers panelCollapsed/panelExpanded events - see makeResizable(). +## DIRECTION\_VERTICAL : string +Represents the vertical direction. **Kind**: global variable + + +## DIRECTION\_HORIZONTAL : string +Represents the horizontal direction. + +**Kind**: global variable + + +## POSITION\_TOP : string +Indicates the top position. + +**Kind**: global variable + + +## POSITION\_BOTTOM : string +Indicates the bottom position. + +**Kind**: global variable + + +## POSITION\_LEFT : string +Indicates the left position. + +**Kind**: global variable + + +## POSITION\_RIGHT : string +Indicates the right position. + +**Kind**: global variable + + +## PREFS\_PURE\_CODE : string +Preference for a distraction-free mode. + +**Kind**: global variable + + +## EVENT\_PANEL\_COLLAPSED : string +Event triggered when a panel is collapsed. + +**Kind**: global constant + + +## EVENT\_PANEL\_EXPANDED : string +Event triggered when a panel is expanded. + +**Kind**: global constant + + +## EVENT\_PANEL\_RESIZE\_START : string +Event triggered at the start of panel resizing. + +**Kind**: global constant + + +## EVENT\_PANEL\_RESIZE\_UPDATE : string +Event triggered during panel resizing updates. + +**Kind**: global constant + + +## EVENT\_PANEL\_RESIZE\_END : string +Event triggered at the end of panel resizing. + +**Kind**: global constant ## show(element) @@ -34,7 +100,8 @@ Hides a resizable element. ## toggle(element) -Changes the visibility state of a resizable element. The toggle functionality is added when an element is made resizable. +Changes the visibility state of a resizable element. The toggle +functionality is added when an element is made resizable. **Kind**: global function @@ -56,7 +123,8 @@ Removes the resizability of an element if it's resizable ## resyncSizer(element) -Updates the sizing div by resyncing to the sizing edge of the element Call this method after manually changing the size of the element +Updates the sizing div by resyncing to the sizing edge of the element +Call this method after manually changing the size of the element **Kind**: global function @@ -79,7 +147,25 @@ Returns the visibility state of a resizable element. ## makeResizable(element, direction, position, minSize, collapsible, forceLeft, createdByWorkspaceManager, usePercentages, forceRight, _attachToParent, [initialSize]) -Adds resizing and (optionally) expand/collapse capabilities to a given html element. The element's size & visibility are automatically saved & restored as a view-state preference. Resizing can be configured in two directions: - Vertical ("vert"): Resizes the height of the element - Horizontal ("horz"): Resizes the width of the element Resizer handlers can be positioned on the element at: - Top ("top") or bottom ("bottom") for vertical resizing - Left ("left") or right ("right") for horizontal resizing A resizable element triggers the following events while resizing: - panelResizeStart: When the resize starts. Passed the new size. - panelResizeUpdate: When the resize gets updated. Passed the new size. - panelResizeEnd: When the resize ends. Passed the final size. - panelCollapsed: When the panel gets collapsed (or hidden). Passed the last size before collapse. May occur without any resize events. - panelExpanded: When the panel gets expanded (or shown). Passed the initial size. May occur without any resize events. +Adds resizing and (optionally) expand/collapse capabilities to a given html element. The element's size +& visibility are automatically saved & restored as a view-state preference. + +Resizing can be configured in two directions: + - Vertical ("vert"): Resizes the height of the element + - Horizontal ("horz"): Resizes the width of the element + +Resizer handlers can be positioned on the element at: + - Top ("top") or bottom ("bottom") for vertical resizing + - Left ("left") or right ("right") for horizontal resizing + +A resizable element triggers the following events while resizing: + - panelResizeStart: When the resize starts. Passed the new size. + - panelResizeUpdate: When the resize gets updated. Passed the new size. + - panelResizeEnd: When the resize ends. Passed the final size. + - panelCollapsed: When the panel gets collapsed (or hidden). Passed the last size + before collapse. May occur without any resize events. + - panelExpanded: When the panel gets expanded (or shown). Passed the initial size. + May occur without any resize events. **Kind**: global function diff --git a/docs/API-Reference/utils/StringMatch.md b/docs/API-Reference/utils/StringMatch.md index 7f2d8c948c..77a4a0e017 100644 --- a/docs/API-Reference/utils/StringMatch.md +++ b/docs/API-Reference/utils/StringMatch.md @@ -9,40 +9,45 @@ const StringMatch = brackets.getModule("utils/StringMatch") Object representing a search result with associated metadata (added as extra ad hoc fields) **Kind**: global function - + -## \_computeRangesAndScore(matchList, original, character) ⇒ Object -Converts a list of matches into a form suitable for returning from stringMatch. +## stringMatch(str, query, options, special) ⇒ Object +Match str against the query using the QuickOpen algorithm provided by +the functions above. The general idea is to prefer matches of "special" characters and, +optionally, matches that occur in the "last segment" (generally, the filename). stringMatch +will try to provide the best match and produces a "matchGoodness" score +to allow for relative ranking. -**Kind**: global function -**Returns**: Object - matched ranges and score - -| Param | Type | Description | -| --- | --- | --- | -| matchList | Array.<(SpecialMatch\|NormalMatch)> | to convert | -| original | string | string | -| character | int | index where last segment begins | - - +The result object returned includes "stringRanges" which can be used to highlight +the matched portions of the string, in addition to the "matchGoodness" +mentioned above. If DEBUG_SCORES is true, scoreDebug is set on the result +to provide insight into the score. -## \_codeHintsRelevanceSort(result, query, [prefixListLower], [maxResults], onlyContiguous) ⇒ Array \| \* -Computes the most relevant ordering for code hints. +The matching is done in a case-insensitive manner. **Kind**: global function -**Returns**: Array \| \* - - The ordered results. +**Returns**: Object - matched ranges and score | Param | Type | Description | | --- | --- | --- | -| result | Array | The array of results to be ordered. | -| query | string | The query string used for matching. | -| [prefixListLower] | Array.<string> | Optional array of result values, that will rank matching items in the choices to the top if the query starts with the array. For example, on typing 'b', we have to show 'background-color' at the top. So we pass in ["background-color"] as a boost prefix list option along with other CSS properties that we want to boost in the results. | -| [maxResults] | number | Optional maximum number of results to include in the output. | -| onlyContiguous | boolean | If set, will only include contiguous results. | +| str | string | The string to search | +| query | string | The query string to find in string | +| options | Object | to control search behavior. preferPrefixMatches puts an exact case-insensitive prefix match ahead of all other matches, even short-circuiting the match logic. This option implies segmentedSearch=false. When segmentedSearch is true, the string is broken into segments by "/" characters and the last segment is searched first and matches there are scored higher. | +| special | Object | (optional) the specials data from findSpecialCharacters, if already known This is generally just used by StringMatcher for optimization. | ## multiFieldSort(searchResults, fieldSpec) -Sorts an array of SearchResult objects on a primary field, followed by secondary fields in case of ties. 'fieldSpec' provides the priority order for fields, where the first entry is the primary field, for example: multiFieldSort(bugList, [ "milestone", "severity" ]); Would sort a bug list by milestone, and within each milestone sort bugs by severity. fieldSpec can also include comparator functions of the form normally used by the sort() function. Any fields that have a string value are compared case-insensitively. Fields used should be present on all SearchResult objects (no optional/undefined fields). +Sorts an array of SearchResult objects on a primary field, followed by secondary fields +in case of ties. 'fieldSpec' provides the priority order for fields, where the first entry is the primary field, for example: + multiFieldSort(bugList, [ "milestone", "severity" ]); +Would sort a bug list by milestone, and within each milestone sort bugs by severity. + +fieldSpec can also include comparator functions of the form normally used by the sort() +function. + +Any fields that have a string value are compared case-insensitively. Fields used should be +present on all SearchResult objects (no optional/undefined fields). **Kind**: global function @@ -54,7 +59,9 @@ Sorts an array of SearchResult objects on a primary field, followed by secondary ## basicMatchSort() -Sorts search results generated by stringMatch(): results are sorted into several tiers based on how well they matched the search query, then sorted alphabetically within each tier. +Sorts search results generated by stringMatch(): results are sorted into several +tiers based on how well they matched the search query, then sorted alphabetically +within each tier. **Kind**: global function @@ -77,7 +84,12 @@ Retrieves the matching code hints based on the given query and choices array. ## StringMatcher(options) -A StringMatcher provides an interface to the stringMatch function with built-in caching. You should use a StringMatcher for the lifetime of queries over a single data set. You are free to store other data on this object to assist in higher-level caching. (This object's caches are all stored in "_" prefixed properties.) +A StringMatcher provides an interface to the stringMatch function with built-in +caching. You should use a StringMatcher for the lifetime of queries over a +single data set. + +You are free to store other data on this object to assist in higher-level caching. +(This object's caches are all stored in "_" prefixed properties.) **Kind**: global function @@ -87,23 +99,9 @@ A StringMatcher provides an interface to the stringMatch function with built-in * [StringMatcher(options)](#StringMatcher) - * [._specialsCache](#StringMatcher+_specialsCache) : Object - * [._noMatchCache](#StringMatcher+_noMatchCache) : Object * [.reset()](#StringMatcher+reset) * [.match(str, query)](#StringMatcher+match) ⇒ Object - - -### stringMatcher.\_specialsCache : Object -Map from search-result string to the findSpecialCharacters() result for that string - easy to cache since this info doesn't change as the query changes. - -**Kind**: instance property of [StringMatcher](#StringMatcher) - - -### stringMatcher.\_noMatchCache : Object -Set of search-result strings that we know don't match the query _lastQuery - or any other query with that prefix. - -**Kind**: instance property of [StringMatcher](#StringMatcher) ### stringMatcher.reset() diff --git a/docs/API-Reference/utils/StringUtils.md b/docs/API-Reference/utils/StringUtils.md index 47571ef7df..a0bca10e21 100644 --- a/docs/API-Reference/utils/StringUtils.md +++ b/docs/API-Reference/utils/StringUtils.md @@ -11,20 +11,26 @@ Utilities functions related to string manipulation * [utils/StringUtils](#module_utils/StringUtils) * [.format(str, Arguments)](#module_utils/StringUtils..format) ⇒ string + * [.regexEscape(str)](#module_utils/StringUtils..regexEscape) ⇒ string + * [.jQueryIdEscape(str)](#module_utils/StringUtils..jQueryIdEscape) ⇒ string * [.getLines(text)](#module_utils/StringUtils..getLines) ⇒ Array.<string> * [.offsetToLineNum(textOrLines, offset)](#module_utils/StringUtils..offsetToLineNum) ⇒ number * [.startsWith(str, prefix)](#module_utils/StringUtils..startsWith) ⇒ Boolean * [.endsWith(str, suffix)](#module_utils/StringUtils..endsWith) + * [.urlSort(a, b)](#module_utils/StringUtils..urlSort) ⇒ number * [.breakableUrl(url)](#module_utils/StringUtils..breakableUrl) ⇒ string * [.prettyPrintBytes(bytes, precision)](#module_utils/StringUtils..prettyPrintBytes) ⇒ string * [.truncate(str, len)](#module_utils/StringUtils..truncate) ⇒ string * [.hashCode(str)](#module_utils/StringUtils..hashCode) ⇒ number * [.randomString(stringLength, [prefix])](#module_utils/StringUtils..randomString) ⇒ string + * [.isNumber(value)](#module_utils/StringUtils..isNumber) ⇒ boolean ### utils/StringUtils.format(str, Arguments) ⇒ string -Format a string by replacing placeholder symbols with passed in arguments. Example: var formatted = StringUtils.format("Hello {0}", "World"); +Format a string by replacing placeholder symbols with passed in arguments. + +Example: var formatted = StringUtils.format("Hello {0}", "World"); **Kind**: inner method of [utils/StringUtils](#module_utils/StringUtils) **Returns**: string - Formatted string @@ -34,6 +40,29 @@ Format a string by replacing placeholder symbols with passed in arguments. Exam | str | string | The base string | | Arguments | rest | to be substituted into the string | + + +### utils/StringUtils.regexEscape(str) ⇒ string +Regex escape + +**Kind**: inner method of [utils/StringUtils](#module_utils/StringUtils) + +| Param | Type | +| --- | --- | +| str | string | + + + +### utils/StringUtils.jQueryIdEscape(str) ⇒ string +Periods (aka "dots") are allowed in HTML identifiers, but jQuery interprets +them as the start of a class selector, so they need to be escaped + +**Kind**: inner method of [utils/StringUtils](#module_utils/StringUtils) + +| Param | Type | +| --- | --- | +| str | string | + ### utils/StringUtils.getLines(text) ⇒ Array.<string> @@ -49,7 +78,13 @@ Splits the text by new line characters and returns an array of lines ### utils/StringUtils.offsetToLineNum(textOrLines, offset) ⇒ number -Returns a line number corresponding to an offset in some text. The text can be specified as a single string or as an array of strings that correspond to the lines of the string. Specify the text in lines when repeatedly calling the function on the same text in a loop. Use getLines() to divide the text into lines, then repeatedly call this function to compute a line number from the offset. +Returns a line number corresponding to an offset in some text. The text can +be specified as a single string or as an array of strings that correspond to +the lines of the string. + +Specify the text in lines when repeatedly calling the function on the same +text in a loop. Use getLines() to divide the text into lines, then repeatedly call +this function to compute a line number from the offset. **Kind**: inner method of [utils/StringUtils](#module_utils/StringUtils) **Returns**: number - line number @@ -83,6 +118,19 @@ Returns true if the given string ends with the given suffix. | str | string | | suffix | string | + + +### utils/StringUtils.urlSort(a, b) ⇒ number +sort two urls alphabetically +ensure folders appear before files on windows + +**Kind**: inner method of [utils/StringUtils](#module_utils/StringUtils) + +| Param | Type | +| --- | --- | +| a | string | +| b | string | + ### utils/StringUtils.breakableUrl(url) ⇒ string @@ -98,7 +146,8 @@ Return an escaped path or URL string that can be broken near path separators. ### utils/StringUtils.prettyPrintBytes(bytes, precision) ⇒ string -Converts number of bytes into human readable format. If param bytes is negative it returns the number without any changes. +Converts number of bytes into human readable format. +If param bytes is negative it returns the number without any changes. **Kind**: inner method of [utils/StringUtils](#module_utils/StringUtils) @@ -123,7 +172,8 @@ Truncate text to specified length. ### utils/StringUtils.hashCode(str) ⇒ number -Computes a 32bit hash from the given string Taken from http://stackoverflow.com/questions/7616461/generate-a-hash-from-string-in-javascript-jquery +Computes a 32bit hash from the given string +Taken from http://stackoverflow.com/questions/7616461/generate-a-hash-from-string-in-javascript-jquery **Kind**: inner method of [utils/StringUtils](#module_utils/StringUtils) **Returns**: number - The 32-bit hash @@ -136,7 +186,9 @@ Computes a 32bit hash from the given string Taken from http://stackoverflow.com/ ### utils/StringUtils.randomString(stringLength, [prefix]) ⇒ string -Generates a random nonce string of the specified length. !!!Should not be used for crypto secure workflows.!!! +Generates a random nonce string of the specified length. + +!!!Should not be used for crypto secure workflows.!!! **Kind**: inner method of [utils/StringUtils](#module_utils/StringUtils) **Returns**: string - - The randomly generated nonce. @@ -146,3 +198,15 @@ Generates a random nonce string of the specified length. !!!Should not be used | stringLength | number | 10 | The length of the nonce in bytes. default 10. | | [prefix] | string | | optional prefix | + + +### utils/StringUtils.isNumber(value) ⇒ boolean +Check if value is a valid number + +**Kind**: inner method of [utils/StringUtils](#module_utils/StringUtils) +**Returns**: boolean - true if value is valid number, else false + +| Param | Type | +| --- | --- | +| value | string | + diff --git a/docs/API-Reference/utils/TokenUtils.md b/docs/API-Reference/utils/TokenUtils.md new file mode 100644 index 0000000000..f3aab0d8cb --- /dev/null +++ b/docs/API-Reference/utils/TokenUtils.md @@ -0,0 +1,122 @@ +### Import : +```js +const TokenUtils = brackets.getModule("utils/TokenUtils") +``` + + + +## \_ +Functions for iterating through tokens in the current editor buffer. Useful for doing +light parsing that can rely purely on information gathered by the code coloring mechanism. + +**Kind**: global variable + + +## getTokenAt(cm, pos, precise) ⇒ Object +Like cm.getTokenAt, but with caching. Way more performant for long lines. + +**Kind**: global function +**Returns**: Object - Token for position + +| Param | Type | Description | +| --- | --- | --- | +| cm | CodeMirror | | +| pos | Object | | +| precise | boolean | If given, results in more current results. Suppresses caching. | + + + +## getInitialContext(cm, pos) ⇒ Object +Creates a context object for the given editor and position, suitable for passing to the +move functions. + +**Kind**: global function + +| Param | Type | +| --- | --- | +| cm | CodeMirror | +| pos | Object | + + + +## movePrevToken(ctx, [precise]) ⇒ boolean +Moves the given context backwards by one token. + +**Kind**: global function +**Returns**: boolean - whether the context changed + +| Param | Type | Description | +| --- | --- | --- | +| ctx | Object | | +| [precise] | boolean | If code is being edited, use true (default) for accuracy. If parsing unchanging code, use false to use cache for performance. | + + + +## isAtStart(ctx) ⇒ boolean +**Kind**: global function +**Returns**: boolean - true if movePrevToken() would return false without changing pos + +| Param | Type | +| --- | --- | +| ctx | Object | + + + +## moveNextToken(ctx, [precise]) ⇒ boolean +Moves the given context forward by one token. + +**Kind**: global function +**Returns**: boolean - whether the context changed + +| Param | Type | Description | +| --- | --- | --- | +| ctx | Object | | +| [precise] | boolean | If code is being edited, use true (default) for accuracy. If parsing unchanging code, use false to use cache for performance. | + + + +## isAtEnd(ctx) ⇒ boolean +**Kind**: global function +**Returns**: boolean - true if moveNextToken() would return false without changing pos + +| Param | Type | +| --- | --- | +| ctx | Object | + + + +## moveSkippingWhitespace(moveFxn, ctx) ⇒ boolean +Moves the given context in the given direction, skipping any whitespace it hits. + +**Kind**: global function +**Returns**: boolean - whether the context changed + +| Param | Type | Description | +| --- | --- | --- | +| moveFxn | function | the function to move the context | +| ctx | Object | | + + + +## offsetInToken(context) ⇒ number +In the given context, get the character offset of pos from the start of the token. + +**Kind**: global function + +| Param | Type | +| --- | --- | +| context | Object | + + + +## getModeAt(cm, pos, precise) ⇒ Object +Returns the mode object and mode name string at a given position + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| cm | CodeMirror | CodeMirror instance | +| pos | Object | Position to query for mode | +| precise | boolean | If given, results in more current results. Suppresses caching. | + diff --git a/docs/API-Reference/utils/ViewUtils.md b/docs/API-Reference/utils/ViewUtils.md index b63c037a8c..b11fe7d344 100644 --- a/docs/API-Reference/utils/ViewUtils.md +++ b/docs/API-Reference/utils/ViewUtils.md @@ -3,21 +3,6 @@ const ViewUtils = brackets.getModule("utils/ViewUtils") ``` - - -## \_updateScrollerShadow($displayElement, $scrollElement, $shadowTop, $shadowBottom, isPositionFixed) -Positions shadow background elements to indicate vertical scrolling. - -**Kind**: global function - -| Param | Type | Description | -| --- | --- | --- | -| $displayElement | DOMElement | the DOMElement that displays the shadow | -| $scrollElement | Object | the object that is scrolled | -| $shadowTop | DOMElement | div .scroller-shadow.top | -| $shadowBottom | DOMElement | div .scroller-shadow.bottom | -| isPositionFixed | boolean | When using absolute position, top remains at 0. | - ## addScrollerShadow(displayElement, scrollElement, showBottom) @@ -59,7 +44,13 @@ Utility function to replace jQuery.toggleClass when used with the second argumen ## sidebarList(scrollElement, selectedClassName) -Within a scrolling DOMElement, creates and positions a styled selection div to align a single selected list item from a ul list element. Assumptions: - scrollerElement is a child of the #sidebar div - ul list element fires a "selectionChanged" event after the selectedClassName is assigned to a new list item +Within a scrolling DOMElement, creates and positions a styled selection +div to align a single selected list item from a ul list element. + +Assumptions: +- scrollerElement is a child of the #sidebar div +- ul list element fires a "selectionChanged" event after the + selectedClassName is assigned to a new list item **Kind**: global function @@ -84,7 +75,17 @@ Determine how much of an element rect is clipped in view. ## scrollElementIntoView($view, $element, scrollHorizontal) -Within a scrolling DOMElement, if necessary, scroll element into viewport. To Perform the minimum amount of scrolling necessary, cases should be handled as follows: - element already completely in view : no scrolling - element above viewport : scroll view so element is at top - element left of viewport : scroll view so element is at left - element below viewport : scroll view so element is at bottom - element right of viewport : scroll view so element is at right Assumptions: - $view is a scrolling container +Within a scrolling DOMElement, if necessary, scroll element into viewport. + +To Perform the minimum amount of scrolling necessary, cases should be handled as follows: +- element already completely in view : no scrolling +- element above viewport : scroll view so element is at top +- element left of viewport : scroll view so element is at left +- element below viewport : scroll view so element is at bottom +- element right of viewport : scroll view so element is at right + +Assumptions: +- $view is a scrolling container **Kind**: global function @@ -109,7 +110,8 @@ HTML formats a file entry name for display in the sidebar. ## getDirNamesForDuplicateFiles(files) ⇒ Array.<string> -Determine the minimum directory path to distinguish duplicate file names for each file in list. +Determine the minimum directory path to distinguish duplicate file names +for each file in list. **Kind**: global function **Returns**: Array.<string> - directory paths to match list of files @@ -118,3 +120,15 @@ Determine the minimum directory path to distinguish duplicate file names for eac | --- | --- | --- | | files | Array.<File> | list of Files with the same filename | + + +## hideMainToolBar() +Hides the main toolbar + +**Kind**: global function + + +## showMainToolBar() +Shows the main toolbar + +**Kind**: global function diff --git a/src/utils/AppInit.js b/src/utils/AppInit.js index cdb09d86f7..b3bcae03a4 100644 --- a/src/utils/AppInit.js +++ b/src/utils/AppInit.js @@ -36,36 +36,41 @@ define(function (require, exports, module) { const Metrics = require("utils/Metrics"); - /* + /** * Fires when the base htmlContent/main-view.html is loaded + * * @type {string} * @const */ var HTML_READY = "htmlReady"; - /* + /** * Fires when all extensions are loaded + * * @type {string} * @const */ var APP_READY = "appReady"; - /* + /** * Fires after extensions have been loaded + * * @type {string} * @const */ var EXTENSIONS_LOADED = "extensionsLoaded"; - /* + /** * Map of each state's trigger + * * @type {Object.} * @private */ var _status = { HTML_READY: false, APP_READY: false, EXTENSIONS_LOADED: false }; - /* + /** * Map of callbacks to states + * * @type {Object.>} * @private */ @@ -76,8 +81,9 @@ define(function (require, exports, module) { _callbacks[EXTENSIONS_LOADED] = []; - /* + /** * calls the specified handler inside a try/catch handler + * * @param {function()} handler - the callback to call * @private */ @@ -98,8 +104,9 @@ define(function (require, exports, module) { } } - /* + /** * dispatches the event by calling all handlers registered for that type + * * @param {string} type - the event type to dispatch (APP_READY, EXTENSIONS_READY, HTML_READY) * @private */ @@ -118,10 +125,11 @@ define(function (require, exports, module) { _callbacks[type] = []; } - /* + /** * adds a callback to the list of functions to call for the specified event type + * * @param {string} type - the event type to dispatch (APP_READY, EXTENSIONS_READY, HTML_READY) - * @param {function} handler - callback funciton to call when the event is triggered + * @param {function} handler - callback function to call when the event is triggered * @private */ function _addListener(type, handler) { @@ -136,6 +144,7 @@ define(function (require, exports, module) { * Adds a callback for the ready hook. Handlers are called after * htmlReady is done, the initial project is loaded, and all extensions are * loaded. + * * @param {function} handler - callback function to call when the event is fired */ function appReady(handler) { @@ -145,6 +154,7 @@ define(function (require, exports, module) { /** * Adds a callback for the htmlReady hook. Handlers are called after the * main application html template is rendered. + * * @param {function} handler - callback function to call when the event is fired */ function htmlReady(handler) { @@ -154,6 +164,7 @@ define(function (require, exports, module) { /** * Adds a callback for the extensionsLoaded hook. Handlers are called after the * extensions have been loaded + * * @param {function} handler - callback function to call when the event is fired */ function extensionsLoaded(handler) { diff --git a/src/utils/Async.js b/src/utils/Async.js index 4e8c9640d5..21cdb8c93e 100644 --- a/src/utils/Async.js +++ b/src/utils/Async.js @@ -308,7 +308,10 @@ define(function (require, exports, module) { return masterDeferred.promise(); } - /** Value passed to fail() handlers that have been triggered due to withTimeout()'s timeout */ + /** + * Value passed to fail() handlers that have been triggered due to withTimeout()'s timeout + * @type {Object} + */ var ERROR_TIMEOUT = {}; /** @@ -435,7 +438,7 @@ define(function (require, exports, module) { try { var responseOrPromise = nextFunction.apply(null, args); if (responseOrPromise.hasOwnProperty("done") && - responseOrPromise.hasOwnProperty("fail")) { + responseOrPromise.hasOwnProperty("fail")) { responseOrPromise.done(function () { chainHelper(index, arguments); }); @@ -509,6 +512,7 @@ define(function (require, exports, module) { * queue at any time. If the queue is empty and nothing is currently executing when an operation is added, * it will execute immediately. Otherwise, it will execute when the last operation currently in the queue * has finished. + * * @constructor */ function PromiseQueue() { @@ -547,6 +551,7 @@ define(function (require, exports, module) { * finished. The operation must return a promise that will be resolved or rejected when it's finished; * the queue will continue with the next operation regardless of whether the current operation's promise * is resolved or rejected. + * * @param {function(): $.Promise} op The operation to add to the queue. */ PromiseQueue.prototype.add = function (op) { @@ -568,8 +573,9 @@ define(function (require, exports, module) { }; /** - * @private * Pulls the next operation off the queue and executes it. + * + * @private */ PromiseQueue.prototype._doNext = function () { var self = this; diff --git a/src/utils/ColorUtils.js b/src/utils/ColorUtils.js index fd388273db..629404d316 100644 --- a/src/utils/ColorUtils.js +++ b/src/utils/ColorUtils.js @@ -31,6 +31,7 @@ define(function (require, exports, module) { /** * 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 + * * @const @type {Array} */ const COLOR_NAMES = ["aliceblue", "antiquewhite", "aqua", "aquamarine", "azure", "beige", "bisque", "black", @@ -60,13 +61,15 @@ define(function (require, exports, module) { * 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. + * * @const @type {RegExp} */ - // use RegExp.source of the RegExp literal to avoid doubled backslashes + // use RegExp.source of the RegExp literal to avoid doubled backslashes var COLOR_REGEX = new RegExp(/0x([a-f0-9]{6})\b|0x([a-f0-9]{8})\b|#[a-f0-9]{6}\b|#[a-f0-9]{8}\b|#[a-f0-9]{3}\b|#[a-f0-9]{4}\b|\brgb\(\s*(?:[0-9]{1,2}|1[0-9]{2}|2[0-4][0-9]|25[0-5])\b\s*,\s*(?:[0-9]{1,2}|1[0-9]{2}|2[0-4][0-9]|25[0-5])\b\s*,\s*(?:[0-9]{1,2}|1[0-9]{2}|2[0-4][0-9]|25[0-5])\b\s*\)|\brgb\(\s*(?:[0-9]{1,2}%|100%)\s*,\s*(?:[0-9]{1,2}%|100%)\s*,\s*(?:[0-9]{1,2}%|100%)\s*\)|\brgba\(\s*(?:[0-9]{1,2}|1[0-9]{2}|2[0-4][0-9]|25[0-5])\b\s*,\s*(?:[0-9]{1,2}|1[0-9]{2}|2[0-4][0-9]|25[0-5])\b\s*,\s*(?:[0-9]{1,2}|1[0-9]{2}|2[0-4][0-9]|25[0-5])\b\s*,\s*(?:1|1\.0|0|0?\.[0-9]{1,3})\s*\)|\brgba\(\s*(?:[0-9]{1,2}%|100%)\s*,\s*(?:[0-9]{1,2}%|100%)\s*,\s*(?:[0-9]{1,2}%|100%)\s*,\s*(?:1|1\.0|0|0?\.[0-9]{1,3})\s*\)|\bhsl\(\s*(?:[0-9]{1,3})\b\s*,\s*(?:[0-9]{1,2}|100)\b%\s*,\s*(?:[0-9]{1,2}|100)\b%\s*\)|\bhsla\(\s*(?:[0-9]{1,3})\b\s*,\s*(?:[0-9]{1,2}|100)\b%\s*,\s*(?:[0-9]{1,2}|100)\b%\s*,\s*(?:1|1\.0|0|0?\.[0-9]{1,3})\s*\)|\b/.source + COLOR_NAMES.join("\\b|\\b") + "\\b", "gi"); - /* + /** * Adds a color swatch to code hints where this is supported. + * * @param {!jQuery} $hintObj - list item where the swatch will be in * @param {?string} color - color the swatch should have, or null to add extra left margin to * align with the other hints diff --git a/src/utils/DeprecationWarning.js b/src/utils/DeprecationWarning.js index b178ec6c50..7832cd7780 100644 --- a/src/utils/DeprecationWarning.js +++ b/src/utils/DeprecationWarning.js @@ -37,6 +37,8 @@ define(function (require, exports, module) { * 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 shows * this deprecation warning. + * + * @private */ function _trimStack(stack) { var indexOfFirstRequireJSline; @@ -58,6 +60,7 @@ define(function (require, exports, module) { /** * Show deprecation warning with the call stack if it * has never been displayed before. + * * @param {!string} message The deprecation message to be displayed. * @param {boolean=} oncePerCaller If true, displays the message once for each unique call location. * If false (the default), only displays the message once no matter where it's called from. @@ -126,8 +129,10 @@ define(function (require, exports, module) { /** * Create a deprecation warning and action for updated constants - * @param {!string} old Menu Id - * @param {!string} new Menu Id + * + * @param {Object} obj + * @param {!string} oldId Menu Id + * @param {!string} newId Menu Id */ function deprecateConstant(obj, oldId, newId) { var warning = "Use Menus." + newId + " instead of Menus." + oldId, diff --git a/src/utils/DragAndDrop.js b/src/utils/DragAndDrop.js index 1ca79b92c0..50af3fbab4 100644 --- a/src/utils/DragAndDrop.js +++ b/src/utils/DragAndDrop.js @@ -1,23 +1,23 @@ - /* - * GNU AGPL-3.0 License - * - * Copyright (c) 2021 - present core.ai . All rights reserved. - * Original work Copyright (c) 2013 - 2021 Adobe Systems Incorporated. All rights reserved. - * - * This program is free software: you can redistribute it and/or modify it - * under the terms of the GNU Affero General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License - * for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see https://opensource.org/licenses/AGPL-3.0. - * - */ +/* +* GNU AGPL-3.0 License +* +* Copyright (c) 2021 - present core.ai . All rights reserved. +* Original work Copyright (c) 2013 - 2021 Adobe Systems Incorporated. All rights reserved. +* +* This program is free software: you can redistribute it and/or modify it +* under the terms of the GNU Affero General Public License as published by +* the Free Software Foundation, either version 3 of the License, or +* (at your option) any later version. +* +* This program is distributed in the hope that it will be useful, but WITHOUT +* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License +* for more details. +* +* You should have received a copy of the GNU Affero General Public License +* along with this program. If not, see https://opensource.org/licenses/AGPL-3.0. +* +*/ // @INCLUDE_IN_API_DOCS @@ -46,6 +46,7 @@ define(function (require, exports, module) { /** * Returns true if the drag and drop items contains valid drop objects. + * * @param {Array.} items Array of items being dragged * @return {boolean} True if one or more items can be dropped. */ @@ -74,6 +75,8 @@ define(function (require, exports, module) { * 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. + * + * @private * @param {Array.} files Array of File objects from the event datastructure. URLs are the only drop item that would contain a URI-list. * @param {event} event 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. */ @@ -97,7 +100,8 @@ define(function (require, exports, module) { /** * Open dropped files - * @param {Array.} files Array of files dropped on the application. + * + * @param {Array.} paths Array of file paths dropped on the application. * @return {Promise} Promise that is resolved if all files are opened, or rejected * if there was an error. */ diff --git a/src/utils/DropdownEventHandler.js b/src/utils/DropdownEventHandler.js index a682f3b44e..dcd380ee08 100644 --- a/src/utils/DropdownEventHandler.js +++ b/src/utils/DropdownEventHandler.js @@ -1,23 +1,23 @@ - /* - * GNU AGPL-3.0 License - * - * Copyright (c) 2021 - present core.ai . All rights reserved. - * Original work Copyright (c) 2013 - 2021 Adobe Systems Incorporated. All rights reserved. - * - * This program is free software: you can redistribute it and/or modify it - * under the terms of the GNU Affero General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License - * for more details. - * - * You should have received a copy of the GNU Affero General Public License - * along with this program. If not, see https://opensource.org/licenses/AGPL-3.0. - * - */ +/* +* GNU AGPL-3.0 License +* +* Copyright (c) 2021 - present core.ai . All rights reserved. +* Original work Copyright (c) 2013 - 2021 Adobe Systems Incorporated. All rights reserved. +* +* This program is free software: you can redistribute it and/or modify it +* under the terms of the GNU Affero General Public License as published by +* the Free Software Foundation, either version 3 of the License, or +* (at your option) any later version. +* +* This program is distributed in the hope that it will be useful, but WITHOUT +* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License +* for more details. +* +* You should have received a copy of the GNU Affero General Public License +* along with this program. If not, see https://opensource.org/licenses/AGPL-3.0. +* +*/ // @INCLUDE_IN_API_DOCS @@ -63,8 +63,9 @@ define(function (require, exports, module) { this.scrolling = false; /** - * @private * The selected position in the list; otherwise -1. + * + * @private * @type {number} */ this._selectedIndex = -1; @@ -79,6 +80,7 @@ define(function (require, exports, module) { /** * Convert keydown events into hint list navigation actions. * + * @private * @param {KeyboardEvent} event * @return {boolean} true if key was handled, otherwise false. */ @@ -110,7 +112,7 @@ define(function (require, exports, module) { self._tryToSelect(self.$items.length - 1, -1); } else if (self._selectedIndex !== -1 && - (keyCode === KeyEvent.DOM_VK_RETURN)) { + (keyCode === KeyEvent.DOM_VK_RETURN)) { // Trigger a click handler to commmit the selected item self._selectionHandler(); @@ -133,6 +135,8 @@ define(function (require, exports, module) { /** * PopUpManager callback + * + * @private */ function closeCallback() { KeyBindingManager.removeGlobalKeydownHook(_keydownHook); @@ -158,6 +162,8 @@ define(function (require, exports, module) { /** * Cleanup + * + * @private */ DropdownEventHandler.prototype._cleanup = function () { if (this.$list) { @@ -171,6 +177,8 @@ define(function (require, exports, module) { /** * Try to select item at the given index. If it's disabled or a divider, keep trying by incrementing * index by 'direction' each time (wrapping around if needed). + * + * @private * @param {number} index 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). @@ -207,6 +215,7 @@ define(function (require, exports, module) { }; /** + * @private * @return {number} The number of items per scroll page. */ DropdownEventHandler.prototype._itemsPerPage = function () { @@ -227,6 +236,8 @@ define(function (require, exports, module) { /** * Call selectionCallback with selected index + * + * @private */ DropdownEventHandler.prototype._selectionHandler = function () { @@ -241,7 +252,8 @@ define(function (require, exports, module) { /** * Call selectionCallback with selected item * - * @param {jQueryObject} $item + * @private + * @param {jQueryObject} $link */ DropdownEventHandler.prototype._clickHandler = function ($link) { @@ -289,6 +301,8 @@ define(function (require, exports, module) { /** * Register mouse event handlers + * + * @private */ DropdownEventHandler.prototype._registerMouseEvents = function () { var self = this; @@ -321,6 +335,7 @@ define(function (require, exports, module) { /** * Re-register mouse event handlers + * * @param {!jQueryObject} $list newly updated list object */ DropdownEventHandler.prototype.reRegisterMouseHandlers = function ($list) { diff --git a/src/utils/EventDispatcher.js b/src/utils/EventDispatcher.js index 36a48bfad3..9f2137ffd0 100644 --- a/src/utils/EventDispatcher.js +++ b/src/utils/EventDispatcher.js @@ -140,7 +140,8 @@ /** * Split "event.namespace" string into its two parts; both parts are optional. - * @param {string} eventName Event name and/or trailing ".namespace" + * + * @param {string} eventStr Event name and/or trailing ".namespace" * @return {!{event:string, ns:string}} Uses "" for missing parts. * @type {function} */ @@ -157,6 +158,7 @@ * By default, we consider any events having more than 15 listeners to be leaky. But sometimes there may be * genuine use cases where an event can have a large number of listeners. For those events, it is recommended * to increase the leaky warning threshold individually with this API. + * * @param {string} eventName * @param {number} threshold - The new threshold to set. Will only be set if the new threshold is greater than * the current threshold. @@ -176,6 +178,7 @@ * Adds the given handler function to 'events': a space-separated list of one or more event names, each * with an optional ".namespace" (used by off() - see below). If the handler is already listening to this * event, a duplicate copy is added. + * * @param {string} events * @param {!function(!{type:string, target:!Object}, ...)} fn * @type {function} @@ -230,6 +233,7 @@ * 'events' can be: bare event name, bare .namespace, or event.namespace pair. This yields a set of * matching handlers. If 'fn' is omitted, all these handlers are removed. If 'fn' is provided, * only handlers exactly equal to 'fn' are removed (there may still be >1, if duplicates were added). + * * @param {string} events * @param {?function(!{type:string, target:!Object}, ...)} fn * @type {function} @@ -287,6 +291,7 @@ /** * Attaches a handler so it's only called once (per event in the 'events' list). + * * @param {string} events * @param {?function(!{type:string, target:!Object}, ...)} fn * @type {function} @@ -306,6 +311,7 @@ /** * Invokes all handlers for the given event (in the order they were added). + * * @param {string} eventName * @param {*} ... Any additional args are passed to the event handler after the event object * @type {function} @@ -340,6 +346,7 @@ /** * Adds the EventDispatcher APIs to the given object: on(), one(), off(), and trigger(). May also be * called on a prototype object - each instance will still behave independently. + * * @param {!Object} obj Object to add event-dispatch methods to * @type {function} */ @@ -359,6 +366,7 @@ /** * Utility for calling on() with an array of arguments to pass to event handlers (rather than a varargs * list). makeEventDispatcher() must have previously been called on 'dispatcher'. + * * @param {!Object} dispatcher * @param {string} eventName * @param {!Array.<*>} argsArray @@ -393,6 +401,7 @@ * May be called before makeEventDispatcher(). May be called on a prototype where makeEventDispatcher() * is called separately per instance (i.e. in the constructor). Should be called before clients have * a chance to start calling on(). + * * @param {!Object} obj Event dispatcher object * @param {string} eventName Name of deprecated event * @param {string=} insteadStr Suggested thing to use instead @@ -420,4 +429,3 @@ defineRequire(); } }()); - diff --git a/src/utils/EventManager.js b/src/utils/EventManager.js index 858273785e..dd1ff78c44 100644 --- a/src/utils/EventManager.js +++ b/src/utils/EventManager.js @@ -84,6 +84,7 @@ define(function (require, exports, module) { /** * Returns true is an EventHandler of the given name exists. + * * @param {string} handlerName * @return {boolean} * @type {function} @@ -126,6 +127,7 @@ define(function (require, exports, module) { * bringing in a cross-origin ifrmame say [`http://mydomain.com`], you should add it to the whitelist by setting * `window.Phoenix.TRUSTED_ORIGINS ["http://mydomain.com"] = true;` * + * @private * @function * @global * @listens window#message @@ -177,6 +179,12 @@ define(function (require, exports, module) { triggerEvent(handlerName, eventName, event); }; + /** + * add or remove a domain, in the list of trusted origin + * + * @param {string} origin - the origin to be added or removed + * @param {boolean} isTrusted - if `true` adds the origin to the list, else removes it. + */ function setTrustedOrigin(origin, isTrusted) { if(!isTrusted){ delete eventTrustedOrigins[origin]; diff --git a/src/utils/ExtensionInterface.js b/src/utils/ExtensionInterface.js index c38c3e52d6..53e57095fd 100644 --- a/src/utils/ExtensionInterface.js +++ b/src/utils/ExtensionInterface.js @@ -62,9 +62,20 @@ */ define(function (require, exports, module) { + + /** + * Extension interface registered event + * + * @const + * @type {string} + */ const EVENT_EXTENSION_INTERFACE_REGISTERED = "extensionInterfaceRegistered"; - /* standard named interfaces registered by default extensions*/ + /** + * standard named interfaces registered by default extensions + * + * @private + */ const _DEFAULT_EXTENSIONS_INTERFACE_NAMES = { PHOENIX_LIVE_PREVIEW: "Extn.Phoenix.livePreview" }; @@ -90,6 +101,7 @@ define(function (require, exports, module) { /** * Returns true is an interface of the given name exists. + * * @param {string} extensionInterfaceName * @return {boolean} * @type {function} diff --git a/src/utils/ExtensionLoader.js b/src/utils/ExtensionLoader.js index eec8056a55..e6da735387 100644 --- a/src/utils/ExtensionLoader.js +++ b/src/utils/ExtensionLoader.js @@ -63,10 +63,31 @@ define(function (require, exports, module) { // default async initExtension timeout var EXTENSION_LOAD_TIMOUT_SECONDS = 60, - INIT_EXTENSION_TIMEOUT = EXTENSION_LOAD_TIMOUT_SECONDS * 1000, - EVENT_EXTENSION_LOADED = "load", - EVENT_EXTENSION_DISABLED = "disabled", - EVENT_EXTENSION_LOAD_FAILED = "loadFailed"; + INIT_EXTENSION_TIMEOUT = EXTENSION_LOAD_TIMOUT_SECONDS * 1000; + + /** + * Extension loaded event + * + * @const + * @type {string} + */ + const EVENT_EXTENSION_LOADED = "load"; + + /** + * Extension disabled event + * + * @const + * @type {string} + */ + const EVENT_EXTENSION_DISABLED = "disabled"; + + /** + * Extension load failed event + * + * @const + * @type {string} + */ + const EVENT_EXTENSION_LOAD_FAILED = "loadFailed"; var _init = false, _extensions = {}, @@ -75,6 +96,8 @@ define(function (require, exports, module) { /** * Stores require.js contexts of extensions + * + * @private * @type {Object.} */ var contexts = {}; @@ -96,14 +119,24 @@ define(function (require, exports, module) { /** * Returns the path to the default extensions directory relative to Phoenix base URL + * + * @private */ const DEFAULT_EXTENSIONS_PATH_BASE = "extensions/default"; + + /** + * Responsible to get the default extension path + * + * @returns {string} + */ function getDefaultExtensionPath() { return window.PhoenixBaseURL + DEFAULT_EXTENSIONS_PATH_BASE; } /** * Returns the full path to the development extensions directory. + * + * @private */ function _getExtensionPath() { return pathLib.normalize(Phoenix.VFS.getExtensionDir()); @@ -111,6 +144,8 @@ define(function (require, exports, module) { /** * Returns the full path to the development extensions directory. + * + * @private */ function getDevExtensionPath() { return pathLib.normalize(Phoenix.VFS.getDevExtensionDir()); @@ -129,7 +164,7 @@ define(function (require, exports, module) { /** * Returns the require.js require context used to load an extension * - * @param {!string} name, used to identify the extension + * @param {!string} name used to identify the extension * @return {!Object} A require.js require object used to load the extension, or undefined if * there is no require object with that name */ @@ -138,8 +173,9 @@ define(function (require, exports, module) { } /** - * @private * Get timeout value for rejecting an extension's async initExtension promise. + * + * @private * @return {number} Timeout in milliseconds */ function _getInitExtensionTimeout() { @@ -147,8 +183,9 @@ define(function (require, exports, module) { } /** - * @private * Set timeout for rejecting an extension's async initExtension promise. + * + * @private * @param {number} value Timeout in milliseconds */ function _setInitExtensionTimeout(value) { @@ -156,8 +193,9 @@ define(function (require, exports, module) { } /** - * @private * Loads optional requirejs-config.json file for an extension + * + * @private * @param {Object} baseConfig * @return {$.Promise} */ @@ -200,8 +238,9 @@ define(function (require, exports, module) { } /** - * @private * Loads optional requirejs-config.json file for an extension + * + * @private * @param {Object} baseConfig * @return {$.Promise} */ @@ -223,7 +262,8 @@ define(function (require, exports, module) { /** * Loads the extension module that lives at baseUrl into its own Require.js context * - * @param {!string} name, used to identify the extension + * @private + * @param {!string} name used to identify the extension * @param {!{baseUrl: string}} config object with baseUrl property containing absolute path of extension * @param {string} entryPoint name of the main js file to load * @param {Object} metadata @@ -347,9 +387,9 @@ define(function (require, exports, module) { /** * Loads the extension that lives at baseUrl into its own Require.js context * - * @param {!string} name, used to identify the extension + * @param {!string} name used to identify the extension * @param {!{baseUrl: string}} config object with baseUrl property containing absolute path of extension - * @param {!string} entryPoint, name of the main js file to load + * @param {!string} entryPoint name of the main js file to load * @return {!$.Promise} A promise object that is resolved when the extension is loaded, or rejected * if the extension fails to load or throws an exception immediately when loaded. * (Note: if extension contains a JS syntax error, promise is resolved not rejected). @@ -387,9 +427,10 @@ define(function (require, exports, module) { /** * Runs unit tests for the extension that lives at baseUrl into its own Require.js context * - * @param {!string} name, used to identify the extension + * @private + * @param {!string} name used to identify the extension * @param {!{baseUrl: string}} config object with baseUrl property containing absolute path of extension - * @param {!string} entryPoint, name of the main js file to load + * @param {!string} entryPoint name of the main js file to load * @return {!$.Promise} A promise object that is resolved when all extensions complete loading. */ function _testExtensionByURL(name, config, entryPoint) { @@ -422,9 +463,9 @@ define(function (require, exports, module) { /** * Runs unit tests for the extension that lives at baseUrl into its own Require.js context * - * @param {!string} name, used to identify the extension + * @param {!string} name used to identify the extension * @param {!{baseUrl: string}} config object with baseUrl property containing absolute path of extension - * @param {!string} entryPoint, name of the main js file to load + * @param {!string} entryPoint name of the main js file to load * @return {!$.Promise} A promise object that is resolved when all extensions complete loading. */ function testExtension(name, config, entryPoint) { @@ -501,9 +542,9 @@ define(function (require, exports, module) { /** - * @private * Loads a file entryPoint from each extension folder within the baseUrl into its own Require.js context * + * @private * @param {!string} directory an absolute native path that contains a directory of extensions. * each subdirectory is interpreted as an independent extension * @param {!string} entryPoint Module name to load (without .js suffix) @@ -572,7 +613,7 @@ define(function (require, exports, module) { /** * Loads the extension that lives at baseUrl into its own Require.js context * - * @param {!string} directory, an absolute native path that contains a directory of extensions. + * @param {!string} directory an absolute native path that contains a directory of extensions. * each subdirectory is interpreted as an independent extension * @return {!$.Promise} A promise object that is resolved when all extensions complete loading. */ @@ -582,6 +623,7 @@ define(function (require, exports, module) { /** * Loads a given extension at the path from virtual fs. Used by `debug menu> load project as extension` + * * @param directory * @return {!Promise} */ @@ -598,7 +640,7 @@ define(function (require, exports, module) { /** * Runs unit test for the extension that lives at baseUrl into its own Require.js context * - * @param {!string} directory, an absolute native path that contains a directory of extensions. + * @param {!string} directory an absolute native path that contains a directory of extensions. * each subdirectory is interpreted as an independent extension * @return {!$.Promise} A promise object that is resolved when all extensions complete loading. */ @@ -702,6 +744,12 @@ define(function (require, exports, module) { // eg: extensionPath = /tauri/home/home/.local/share/io.phcode.dev/assets/extensions/devTemp/theme/14/theme.css // eg: customExtensionLoadPath = /tauri/home/home/.local/share/io.phcode.dev/assets/extensions/devTemp/theme/14 // eg: srcBasePath = /tauri/home/home/myExtension + /** + * To get the source path for extension + * + * @param extensionPath + * @returns {string} + */ function getSourcePathForExtension(extensionPath) { const devTempExtDir = `${Phoenix.VFS.getDevTempExtensionDir()}/`; if(extensionPath.startsWith(devTempExtDir)) { @@ -756,9 +804,9 @@ define(function (require, exports, module) { } }); }).catch((err)=>{ - console.error(`Error creating dir ${extDestPath}`, err); - result.reject(err); - }); + console.error(`Error creating dir ${extDestPath}`, err); + result.reject(err); + }); }); // custom extensions are always loaded marked as resolved to prevent the main event loop from taking // too long to load diff --git a/src/utils/ExtensionUtils.js b/src/utils/ExtensionUtils.js index 977004ae4a..d4e6519300 100644 --- a/src/utils/ExtensionUtils.js +++ b/src/utils/ExtensionUtils.js @@ -72,6 +72,8 @@ define(function (require, exports, module) { /** * getModuleUrl returns different urls for win platform * so that's why we need a different check here + * + * @private * @see #getModuleUrl * @param {!string} pathOrUrl that should be checked if it's absolute * @return {!boolean} returns true if pathOrUrl is absolute url on win platform @@ -132,7 +134,7 @@ define(function (require, exports, module) { * @param {!module} module Module provided by RequireJS * @param {?string} path Relative path from the extension folder to a file * @return {!string} The path to the module's folder - **/ + */ function getModulePath(module, path) { var modulePath = module.uri.substr(0, module.uri.lastIndexOf("/") + 1); if (path) { @@ -148,7 +150,7 @@ define(function (require, exports, module) { * @param {!module} module Module provided by RequireJS * @param {?string} path Relative path from the extension folder to a file * @return {!string} The URL to the module's folder - **/ + */ function getModuleUrl(module, path) { return encodeURI(getModulePath(module, path)); } @@ -161,7 +163,7 @@ define(function (require, exports, module) { * @param {!module} module Module provided by RequireJS * @param {!string} path Relative path from the extension folder to a file * @return {!$.Promise} A promise object that is resolved with the contents of the requested file - **/ + */ function loadFile(module, path) { var url = PathUtils.isAbsoluteUrl(path) ? path : getModuleUrl(module, path); let result = new $.Deferred(); @@ -226,6 +228,7 @@ define(function (require, exports, module) { * Loads the package.json file in the given extension folder as well as any additional * metadata. * + * @private * @param {string} baseExtensionUrl The extension folder. * @param {?string} extensionName optional extension name * @return {$.Promise} A promise object that is resolved with the parsed contents of the package.json file, @@ -241,18 +244,18 @@ define(function (require, exports, module) { .then(function (packageResult) { json = packageResult; }).always(function () { - // if we don't have any metadata for the extension - // we should still create an empty one, so we can attach - // disabled property on it in case it's disabled - let disabled, - defaultDisabled = JSON.parse(PhStore.getItem(Package.DEFAULT_DISABLED_EXTENSIONS_KEY) || "[]"); - if (Array.isArray(defaultDisabled) && defaultDisabled.indexOf(baseExtensionUrl) !== -1) { - console.warn("Extension has been disabled on startup: " + baseExtensionUrl); - disabled = true; - } - json.disabled = disabled; - result.resolve(json); - }); + // if we don't have any metadata for the extension + // we should still create an empty one, so we can attach + // disabled property on it in case it's disabled + let disabled, + defaultDisabled = JSON.parse(PhStore.getItem(Package.DEFAULT_DISABLED_EXTENSIONS_KEY) || "[]"); + if (Array.isArray(defaultDisabled) && defaultDisabled.indexOf(baseExtensionUrl) !== -1) { + console.warn("Extension has been disabled on startup: " + baseExtensionUrl); + disabled = true; + } + json.disabled = disabled; + result.resolve(json); + }); return result.promise(); } @@ -266,6 +269,7 @@ define(function (require, exports, module) { * disabled might be set. * * @param {string} metadataURL The extension folder/base url for default extensions. + * @param {string} extensionName name of the extension * @return {$.Promise} A promise object that is resolved with the parsed contents of the package.json file, * or rejected if there is no package.json with the boolean indicating whether .disabled file exists. */ diff --git a/src/utils/FeatureGate.js b/src/utils/FeatureGate.js index 8da7b2435d..a54eb03f02 100644 --- a/src/utils/FeatureGate.js +++ b/src/utils/FeatureGate.js @@ -60,9 +60,16 @@ */ define(function (require, exports, module) { - const FEATURE_REGISTERED = "featureGateRegistered", - ENABLED = 'enabled', - DISABLED = 'disabled'; + /** + * Feature gate registered + * + * @const + * @type {string} + */ + const FEATURE_REGISTERED = "featureGateRegistered"; + + const ENABLED = 'enabled'; + const DISABLED = 'disabled'; let EventDispatcher = require("utils/EventDispatcher"); @@ -89,6 +96,7 @@ define(function (require, exports, module) { /** * Returns an array of all named registered feature gates. + * * @return {string[]} list of registered features * @type {function} */ @@ -103,6 +111,7 @@ define(function (require, exports, module) { * if(FeatureGate.isFeatureEnabled(FEATURE_NEW_COLORS)){ * // do fancy colors here * } + * * @param {string} featureName * @return {boolean} * @type {function} diff --git a/src/utils/Global.js b/src/utils/Global.js index ce78de309c..ba44641e52 100644 --- a/src/utils/Global.js +++ b/src/utils/Global.js @@ -19,8 +19,6 @@ * */ -// @INCLUDE_IN_API_DOCS - /** * Initializes the global "brackets" variable and it's properties. * Modules should not access the global.brackets object until either diff --git a/src/utils/KeyEvent.js b/src/utils/KeyEvent.js index f150897f7b..8b86b9aa21 100644 --- a/src/utils/KeyEvent.js +++ b/src/utils/KeyEvent.js @@ -19,8 +19,126 @@ * */ +// @INCLUDE_IN_API_DOCS + /** * Utilities module to provide constants for keyCodes + * @property{number} DOM_VK_CANCEL: 3 + * @property{number} DOM_VK_HELP: 6 + * @property{number} DOM_VK_BACK_SPACE: 8 + * @property{number} DOM_VK_TAB: 9 + * @property{number} DOM_VK_CLEAR: 12 + * @property{number} DOM_VK_RETURN: 13 + * @property{number} DOM_VK_ENTER: 14 + * @property{number} DOM_VK_SHIFT: 16 + * @property{number} DOM_VK_CONTROL: 17 + * @property{number} DOM_VK_ALT: 18 + * @property{number} DOM_VK_PAUSE: 19 + * @property{number} DOM_VK_CAPS_LOCK: 20 + * @property{number} DOM_VK_ESCAPE: 27 + * @property{number} DOM_VK_SPACE: 32 + * @property{number} DOM_VK_PAGE_UP: 33 + * @property{number} DOM_VK_PAGE_DOWN: 34 + * @property{number} DOM_VK_END: 35 + * @property{number} DOM_VK_HOME: 36 + * @property{number} DOM_VK_LEFT: 37 + * @property{number} DOM_VK_UP: 38 + * @property{number} DOM_VK_RIGHT: 39 + * @property{number} DOM_VK_DOWN: 40 + * @property{number} DOM_VK_PRINTSCREEN: 44 + * @property{number} DOM_VK_INSERT: 45 + * @property{number} DOM_VK_DELETE: 46 + * @property{number} DOM_VK_0: 48 + * @property{number} DOM_VK_1: 49 + * @property{number} DOM_VK_2: 50 + * @property{number} DOM_VK_3: 51 + * @property{number} DOM_VK_4: 52 + * @property{number} DOM_VK_5: 53 + * @property{number} DOM_VK_6: 54 + * @property{number} DOM_VK_7: 55 + * @property{number} DOM_VK_8: 56 + * @property{number} DOM_VK_9: 57 + * @property{number} DOM_VK_A: 65 + * @property{number} DOM_VK_B: 66 + * @property{number} DOM_VK_C: 67 + * @property{number} DOM_VK_D: 68 + * @property{number} DOM_VK_E: 69 + * @property{number} DOM_VK_F: 70 + * @property{number} DOM_VK_G: 71 + * @property{number} DOM_VK_H: 72 + * @property{number} DOM_VK_I: 73 + * @property{number} DOM_VK_J: 74 + * @property{number} DOM_VK_K: 75 + * @property{number} DOM_VK_L: 76 + * @property{number} DOM_VK_M: 77 + * @property{number} DOM_VK_N: 78 + * @property{number} DOM_VK_O: 79 + * @property{number} DOM_VK_P: 80 + * @property{number} DOM_VK_Q: 81 + * @property{number} DOM_VK_R: 82 + * @property{number} DOM_VK_S: 83 + * @property{number} DOM_VK_T: 84 + * @property{number} DOM_VK_U: 85 + * @property{number} DOM_VK_V: 86 + * @property{number} DOM_VK_W: 87 + * @property{number} DOM_VK_X: 88 + * @property{number} DOM_VK_Y: 89 + * @property{number} DOM_VK_Z: 90 + * @property{number} DOM_VK_CONTEXT_MENU: 93 + * @property{number} DOM_VK_NUMPAD0: 96 + * @property{number} DOM_VK_NUMPAD1: 97 + * @property{number} DOM_VK_NUMPAD2: 98 + * @property{number} DOM_VK_NUMPAD3: 99 + * @property{number} DOM_VK_NUMPAD4: 100 + * @property{number} DOM_VK_NUMPAD5: 101 + * @property{number} DOM_VK_NUMPAD6: 102 + * @property{number} DOM_VK_NUMPAD7: 103 + * @property{number} DOM_VK_NUMPAD8: 104 + * @property{number} DOM_VK_NUMPAD9: 105 + * @property{number} DOM_VK_MULTIPLY: 106 + * @property{number} DOM_VK_ADD: 107 + * @property{number} DOM_VK_SEPARATOR: 108 + * @property{number} DOM_VK_SUBTRACT: 109 + * @property{number} DOM_VK_DECIMAL: 110 + * @property{number} DOM_VK_DIVIDE: 111 + * @property{number} DOM_VK_F1: 112 + * @property{number} DOM_VK_F2: 113 + * @property{number} DOM_VK_F3: 114 + * @property{number} DOM_VK_F4: 115 + * @property{number} DOM_VK_F5: 116 + * @property{number} DOM_VK_F6: 117 + * @property{number} DOM_VK_F7: 118 + * @property{number} DOM_VK_F8: 119 + * @property{number} DOM_VK_F9: 120 + * @property{number} DOM_VK_F10: 121 + * @property{number} DOM_VK_F11: 122 + * @property{number} DOM_VK_F12: 123 + * @property{number} DOM_VK_F13: 124 + * @property{number} DOM_VK_F14: 125 + * @property{number} DOM_VK_F15: 126 + * @property{number} DOM_VK_F16: 127 + * @property{number} DOM_VK_F17: 128 + * @property{number} DOM_VK_F18: 129 + * @property{number} DOM_VK_F19: 130 + * @property{number} DOM_VK_F20: 131 + * @property{number} DOM_VK_F21: 132 + * @property{number} DOM_VK_F22: 133 + * @property{number} DOM_VK_F23: 134 + * @property{number} DOM_VK_F24: 135 + * @property{number} DOM_VK_NUM_LOCK: 144 + * @property{number} DOM_VK_SCROLL_LOCK: 145 + * @property{number} DOM_VK_SEMICOLON: 186 + * @property{number} DOM_VK_EQUALS: 187 + * @property{number} DOM_VK_COMMA: 188 + * @property{number} DOM_VK_DASH: 189 + * @property{number} DOM_VK_PERIOD: 190 + * @property{number} DOM_VK_SLASH: 191 + * @property{number} DOM_VK_BACK_QUOTE: 192 + * @property{number} DOM_VK_OPEN_BRACKET: 219 + * @property{number} DOM_VK_BACK_SLASH: 220 + * @property{number} DOM_VK_CLOSE_BRACKET: 221 + * @property{number} DOM_VK_QUOTE: 222 + * @property{number} DOM_VK_META: 22 */ define({ DOM_VK_CANCEL: 3, diff --git a/src/utils/NativeApp.js b/src/utils/NativeApp.js index efbe688d55..cf4bcf841c 100644 --- a/src/utils/NativeApp.js +++ b/src/utils/NativeApp.js @@ -19,6 +19,8 @@ * */ +// @INCLUDE_IN_API_DOCS + /** * Virtualized NativeApp apis that works cross-platform, and in the browser. */ @@ -30,8 +32,9 @@ define(function (require, exports, module) { FileSystemError = require("filesystem/FileSystemError"); /** - * @private * Map an fs error code to a FileError. + * + * @private */ function _browserErrToFileError(err) { if (err === brackets.fs.ERR_CODES.NOT_FOUND) { @@ -46,6 +49,7 @@ define(function (require, exports, module) { /** openLiveBrowser * Open the given URL in the user's system browser, optionally enabling debugging. + * * @param {string} url The URL to open. * @param {boolean=} enableRemoteDebugging Whether to turn on remote debugging. Default false. * @return {$.Promise} @@ -95,6 +99,7 @@ define(function (require, exports, module) { /** closeAllLiveBrowsers * Closes all the browsers that were tracked on open + * * TODO: does not seem to work on Windows * @return {$.Promise} */ @@ -106,6 +111,7 @@ define(function (require, exports, module) { /** * Opens a URL in the system default browser. + * * @param {string} url * @param {string?} tabIdentifier - An optional tab identifier can be set to group the tabs. Maps to target option * in browser. Doesn't do anything in tauri. @@ -114,6 +120,9 @@ define(function (require, exports, module) { return brackets.app.openURLInDefaultBrowser(url, tabIdentifier); } + /** + * Gets the path to the application's support directory + */ function getApplicationSupportDirectory() { return brackets.app.getApplicationSupportDirectory(); } diff --git a/src/utils/NodeConnection.js b/src/utils/NodeConnection.js index dc0cf121c9..d3b799598d 100644 --- a/src/utils/NodeConnection.js +++ b/src/utils/NodeConnection.js @@ -19,8 +19,6 @@ * */ -// @INCLUDE_IN_API_DOCS - define(function (require, exports, module) { diff --git a/src/utils/NodeUtils.js b/src/utils/NodeUtils.js index a6cdcb3a37..ce838e65ec 100644 --- a/src/utils/NodeUtils.js +++ b/src/utils/NodeUtils.js @@ -19,6 +19,8 @@ * */ +// @INCLUDE_IN_API_DOCS + /** * Generic node util APIs connector. see `src-node/utils.js` for node peer */ @@ -34,6 +36,14 @@ define(function (require, exports, module) { utilsConnector = NodeConnector.createNodeConnector(UTILS_NODE_CONNECTOR, exports); } + /** + * Fetches text content from a URL + * This is only available in the native app + * + * @param {string} url + * @param {string} encoding + * @return {Promise} + */ async function fetchURLText(url, encoding) { if(!Phoenix.isNativeApp) { throw new Error("node not available in browser"); @@ -44,6 +54,8 @@ define(function (require, exports, module) { /** * updates the localized strings in brackets `Strings` to node. + * + * @private * @return {Promise} Promise resolves to true if strings was updated in node, else false(in browser.) */ async function _updateNodeLocaleStrings() { @@ -55,6 +67,12 @@ define(function (require, exports, module) { return true; } + /** + * Gets the version of the Phoenix binary + * This is only available in the native app + * + * @return {Promise} + */ async function getPhoenixBinaryVersion() { if(!Phoenix.isNativeApp) { throw new Error("getPhoenixBinaryVersion not available in browser"); @@ -64,6 +82,12 @@ define(function (require, exports, module) { return utilsConnector.execPeer("getPhoenixBinaryVersion", phoenixBinPath); } + /** + * Retrieves the Linux OS flavor name + * This is only available in the native app on Linux + * + * @return {Promise} + */ async function getLinuxOSFlavorName() { if(Phoenix.platform !== "linux" || !Phoenix.isNativeApp) { return null; @@ -71,6 +95,13 @@ define(function (require, exports, module) { return utilsConnector.execPeer("getLinuxOSFlavorName"); } + /** + * Opens a URL in the default browser. + * This is only available in the native app. + * + * @param {string} url + * @param {string} browserName + */ async function openUrlInBrowser(url, browserName) { if(!Phoenix.isNativeApp) { throw new Error("openUrlInBrowser not available in browser"); @@ -95,6 +126,13 @@ define(function (require, exports, module) { return utilsConnector.execPeer("_npmInstallInFolder", {moduleNativeDir}); } + /** + * Gets an environment variable's value + * This is only available in the native app + * + * @param {string} varName + * @return {Promise} + */ async function getEnvironmentVariable(varName) { if(!Phoenix.isNativeApp) { throw new Error("getEnvironmentVariable not available in browser"); @@ -102,6 +140,14 @@ define(function (require, exports, module) { return utilsConnector.execPeer("getEnvironmentVariable", varName); } + /** + * Runs ESLint on a file + * This is only available in the native app + * + * @param {string} text + * @param {string} fullFilePath + * @param {string} projectFullPath + */ async function ESLintFile(text, fullFilePath, projectFullPath) { if(!Phoenix.isNativeApp) { throw new Error("ESLintFile not available in browser"); @@ -149,6 +195,12 @@ define(function (require, exports, module) { exports.openUrlInBrowser = openUrlInBrowser; exports.ESLintFile = ESLintFile; exports.getEnvironmentVariable = getEnvironmentVariable; + + /** + * checks if Node connector is ready + * + * @return {boolean} returns true if it's ready, otherwise false + */ exports.isNodeReady = NodeConnector.isNodeReady; window.NodeUtils = exports; diff --git a/src/utils/PerfUtils.js b/src/utils/PerfUtils.js index 4e766fe406..45fa2364ef 100644 --- a/src/utils/PerfUtils.js +++ b/src/utils/PerfUtils.js @@ -36,6 +36,8 @@ define(function (require, exports, module) { /** * Flag to enable/disable performance data gathering. Default is true (enabled) + * + * @private * @type {boolean} enabled */ var enabled = brackets && !!brackets.app.getTimeSinceStartup; @@ -45,12 +47,16 @@ define(function (require, exports, module) { * test (passed to markStart/addMeasurement), and the value is the time, in * milliseconds, that it took to run the test. If multiple runs of the same test * are made, the value is an Array with each run stored as an entry in the Array. + * + * @private */ var perfData = {}; /** * Active tests. This is a hash of all tests that have had markStart() called, * but have not yet had addMeasurement() called. + * + * @private */ var activeTests = {}; @@ -58,20 +64,23 @@ define(function (require, exports, module) { * Updatable tests. This is a hash of all tests that have had markStart() called, * and have had updateMeasurement() called. Caller must explicitly remove tests * from this list using finalizeMeasurement() + * + * @private */ var updatableTests = {}; /** - * @private * Keeps the track of measurements sequence number for re-entrant sequences with * the same name currently running. Entries are created and deleted as needed. + * + * @private */ var _reentTests = {}; /** - * @private * A unique key to log performance data * + * @private * @param {(string|undefined)} id Unique ID for this measurement name * @param {!string} name A short name for this measurement * @param {?number} reent Sequence identifier for parallel tests of the same name @@ -89,6 +98,8 @@ define(function (require, exports, module) { /** * Override toString() to allow using PerfMeasurement as an array key without * explicit conversion. + * + * @private */ PerfMeasurement.prototype.toString = function () { return this.name; @@ -109,8 +120,9 @@ define(function (require, exports, module) { } /** - * @private * Generates PerfMeasurements based on the name or array of names. + * + * @private */ function _generatePerfMeasurements(name) { // always convert it to array so that the rest of the routines could rely on it @@ -131,9 +143,9 @@ define(function (require, exports, module) { } /** - * @private * Helper function for markStart() * + * @private * @param {Object} id Timer id. * @param {number} time Timer start time. */ @@ -305,6 +317,8 @@ define(function (require, exports, module) { /** * return single value, or comma separated values for an array or return aggregated values with * "min value, average, max value, standard deviation" + * + * @private * @param {Array} entry An array or a single value * @param {Boolean} aggregateStats If set, the returned value will be aggregated in the form - * "min(avg)max[standard deviation]" @@ -340,6 +354,7 @@ define(function (require, exports, module) { /** * Returns the performance data as a tab delimited string + * * @return {string} */ function getDelimitedPerfData() { @@ -353,7 +368,8 @@ define(function (require, exports, module) { /** * Returns the measured value for the given measurement name. - * @param {Object} id The measurement to retreive. + * + * @param {Object} id The measurement to retrieve. */ function getData(id) { if (!id) { @@ -365,6 +381,7 @@ define(function (require, exports, module) { /** * Returns the Performance metrics to be logged for health report + * * @return {Object} An object with the health data logs to be sent */ function getHealthReport() { @@ -388,6 +405,11 @@ define(function (require, exports, module) { return healthReport; } + /** + * To search data given the regular expression + * @param {RegExp} regExp the regular expression + * @returns {Array} + */ function searchData(regExp) { var keys = Object.keys(perfData).filter(function (key) { return regExp.test(key); diff --git a/src/utils/Resizer.js b/src/utils/Resizer.js index aae8e558f4..9ae4e29886 100644 --- a/src/utils/Resizer.js +++ b/src/utils/Resizer.js @@ -43,24 +43,97 @@ */ define(function (require, exports, module) { + // Minimum size (height or width) for autodiscovered resizable panels + var DEFAULT_MIN_SIZE = 100; + /** + * Represents the vertical direction. + * + * @type {string} + */ var DIRECTION_VERTICAL = "vert"; + + /** + * Represents the horizontal direction. + * + * @type {string} + */ var DIRECTION_HORIZONTAL = "horz"; + /** + * Indicates the top position. + * + * @type {string} + */ var POSITION_TOP = "top"; + + /** + * Indicates the bottom position. + * + * @type {string} + */ var POSITION_BOTTOM = "bottom"; + + /** + * Indicates the left position. + * + * @type {string} + */ var POSITION_LEFT = "left"; + + /** + * Indicates the right position. + * + * @type {string} + */ var POSITION_RIGHT = "right"; + + /** + * Preference for a distraction-free mode. + * + * @type {string} + */ var PREFS_PURE_CODE = "noDistractions"; - // Minimum size (height or width) for autodiscovered resizable panels - var DEFAULT_MIN_SIZE = 100; + /** + * Event triggered when a panel is collapsed. + * + * @type {string} + * @constant + */ + const EVENT_PANEL_COLLAPSED = 'panelCollapsed'; + + /** + * Event triggered when a panel is expanded. + * + * @type {string} + * @constant + */ + const EVENT_PANEL_EXPANDED = 'panelExpanded'; - const EVENT_PANEL_COLLAPSED = 'panelCollapsed', - EVENT_PANEL_EXPANDED = 'panelExpanded', - EVENT_PANEL_RESIZE_START = 'panelResizeStart', - EVENT_PANEL_RESIZE_UPDATE = 'panelResizeUpdate', - EVENT_PANEL_RESIZE_END = 'panelResizeEnd'; + /** + * Event triggered at the start of panel resizing. + * + * @type {string} + * @constant + */ + const EVENT_PANEL_RESIZE_START = 'panelResizeStart'; + + /** + * Event triggered during panel resizing updates. + * + * @type {string} + * @constant + */ + const EVENT_PANEL_RESIZE_UPDATE = 'panelResizeUpdate'; + + /** + * Event triggered at the end of panel resizing. + * + * @type {string} + * @constant + */ + const EVENT_PANEL_RESIZE_END = 'panelResizeEnd'; // Load dependent modules var AppInit = require("utils/AppInit"), @@ -76,6 +149,7 @@ define(function (require, exports, module) { /** * Shows a resizable element. + * * @param {DOMNode} element Html element to show if possible */ function show(element) { @@ -87,6 +161,7 @@ define(function (require, exports, module) { /** * Hides a resizable element. + * * @param {DOMNode} element Html element to hide if possible */ function hide(element) { @@ -99,6 +174,7 @@ define(function (require, exports, module) { /** * Changes the visibility state of a resizable element. The toggle * functionality is added when an element is made resizable. + * * @param {DOMNode} element Html element to toggle */ function toggle(element) { @@ -111,6 +187,7 @@ define(function (require, exports, module) { /** * Removes the resizability of an element if it's resizable + * * @param {DOMNode} element Html element in which to remove sizing */ function removeSizable(element) { @@ -123,6 +200,7 @@ define(function (require, exports, module) { /** * Updates the sizing div by resyncing to the sizing edge of the element * Call this method after manually changing the size of the element + * * @param {DOMNode} element Html element whose sizer should be resynchronized */ function resyncSizer(element) { @@ -134,6 +212,7 @@ define(function (require, exports, module) { /** * Returns the visibility state of a resizable element. + * * @param {DOMNode} element Html element to toggle * @return {boolean} true if element is visible, false if it is not visible */ @@ -207,8 +286,8 @@ define(function (require, exports, module) { * or current size. */ function makeResizable(element, direction, position, minSize, collapsible, - forceLeft, createdByWorkspaceManager, usePercentages, - forceRight, _attachToParent, initialSize) { + forceLeft, createdByWorkspaceManager, usePercentages, + forceRight, _attachToParent, initialSize) { var $resizer = $('
'), $element = $(element), $parent = $element.parent(), @@ -236,7 +315,7 @@ define(function (require, exports, module) { return this.height(newSize); } - // calling the function as a setter + // calling the function as a setter var parentSize = parentSizeFunction.apply($parent), percentage, prop; @@ -257,7 +336,7 @@ define(function (require, exports, module) { contentSizeFunction = direction === DIRECTION_HORIZONTAL ? $resizableElement.width : $resizableElement.height; if (PreferencesManager.get(PREFS_PURE_CODE) && - ($element.hasClass("bottom-panel") || $element.hasClass("sidebar"))) { + ($element.hasClass("bottom-panel") || $element.hasClass("sidebar"))) { elementPrefs.visible = false; } diff --git a/src/utils/StringMatch.js b/src/utils/StringMatch.js index d959839f34..c8b88e135b 100644 --- a/src/utils/StringMatch.js +++ b/src/utils/StringMatch.js @@ -33,14 +33,16 @@ define(function (require, exports, module) { * Performs matching that is useful for QuickOpen and similar searches. */ - /** Object representing a search result with associated metadata (added as extra ad hoc fields) */ + /** + * Object representing a search result with associated metadata (added as extra ad hoc fields) + */ function SearchResult(label) { this.label = label; } - /* + /** * Identifies the "special" characters in the given string. * Special characters for matching purposes are: * @@ -56,7 +58,8 @@ define(function (require, exports, module) { * beginning of the last path segment. (This is used to allow scanning of * the last segment's specials separately.) * - * @param {string} input string to break apart (e.g. filename that is being searched) + * @private + * @param {string} str input string to break apart (e.g. filename that is being searched) * @return {{specials:Array., lastSegmentSpecialsIndex:number}} */ function findSpecialCharacters(str) { @@ -146,7 +149,7 @@ define(function (require, exports, module) { } } - /* + /** * Finds the best matches between the query and the string. The query is * compared with str (usually a lower case string with a lower case * query). @@ -203,7 +206,7 @@ define(function (require, exports, module) { * * * When `deadBranches[queryCounter] = strCounter` it means if we're still trying to match * `queryLower[queryCounter]` and we get to `str[strCounter]`, there's no way we can match the - * remainer of `queryLower` with the remainder of `str` -- either using specials-only or + * remainder of `queryLower` with the remainder of `str` -- either using specials-only or * full any-char matching. * * * We know this because deadBranches[] is set in backtrack(), and we don't get to backtrack() unless @@ -214,6 +217,7 @@ define(function (require, exports, module) { * (i.e. backtrack() due to `strCounter > deadBranches[queryCounter]`, yet * `queryCounter < query.length`) * + * @private * @param {string} query the search string (generally lower cased) * @param {string} str the string to compare with (generally lower cased) * @param {string} originalQuery the "non-normalized" query string (used to detect case match priority) @@ -388,7 +392,7 @@ define(function (require, exports, module) { } - /* + /** * Seek out the best match in the last segment (generally the filename). * Matches in the filename are preferred, but the query entered could match * any part of the path. So, we find the best match we can get in the filename @@ -400,6 +404,7 @@ define(function (require, exports, module) { * result can optionally include a remainder, which is the characters * at the beginning of the query which did not match in the last segment. * + * @private * @param {string} query the search string (generally lower cased) * @param {string} str the string to compare with (generally lower cased) * @param {string} originalQuery the "non-normalized" query string (used to detect case match priority) @@ -447,12 +452,13 @@ define(function (require, exports, module) { } - /* + /** * Implements the top-level search algorithm. Search the last segment first, * then search the rest of the string with the remainder. * * The parameters and return value are the same as for getMatchRanges. * + * @private * @param {string} queryLower the search string (will be searched lower case) * @param {string} compareLower the lower-cased string to search * @param {string} originalQuery the "non-normalized" query string (used to detect case match priority) @@ -500,6 +506,7 @@ define(function (require, exports, module) { /** * Converts a list of matches into a form suitable for returning from stringMatch. * + * @private * @param {Array.} matchList to convert * @param {string} original string * @param {int} character index where last segment begins @@ -695,12 +702,13 @@ define(function (require, exports, module) { return result; } - /* + /** * If we short circuit normal matching to produce a prefix match, * this function will generate the appropriate SearchResult. * This function assumes that the prefix match check has already * been performed. * + * @private * @param {string} str The string with the prefix match for the query * @param {string} query The query that matched the beginning of str * @return {{ranges:{text:string, matched:boolean, includesLastSegment:boolean}, matchGoodness:int, scoreDebug: Object}} ranges has a matching range for beginning of str @@ -829,12 +837,14 @@ define(function (require, exports, module) { /** * Computes the most relevant ordering for code hints. + * + * @private * @param {Array} result - The array of results to be ordered. * @param {string} query - The query string used for matching. * @param {Array} [prefixListLower] - Optional array of result values, * that will rank matching items in the choices to the top * if the query starts with the array. For example, on typing 'b', we have to show - * 'background-color' at the top. So we pass in ["background-color"] as a boost prefix list option + * 'background-color' at the top. So we pass in ["background-color"] as a boost prefix list option * along with other CSS properties that we want to boost in the results. * @param {number} [maxResults] - Optional maximum number of results to include in the output. * @param {boolean} onlyContiguous - If set, will only include contiguous results. @@ -923,7 +933,7 @@ define(function (require, exports, module) { return orderedResults; } - /* + /** * Match str against the query using the QuickOpen algorithm provided by * the functions above. The general idea is to prefer matches of "special" characters and, * optionally, matches that occur in the "last segment" (generally, the filename). stringMatch @@ -1149,6 +1159,8 @@ define(function (require, exports, module) { /** * Map from search-result string to the findSpecialCharacters() result for that string - easy to cache * since this info doesn't change as the query changes. + * + * @private * @type {{string: {specials:Array., lastSegmentSpecialsIndex:number}}} */ StringMatcher.prototype._specialsCache = null; @@ -1156,6 +1168,8 @@ define(function (require, exports, module) { /** * Set of search-result strings that we know don't match the query _lastQuery - or any other query with * that prefix. + * + * @private * @type {{string: boolean}} */ StringMatcher.prototype._noMatchCache = null; diff --git a/src/utils/StringUtils.js b/src/utils/StringUtils.js index 71aa3dd639..62ab188f52 100644 --- a/src/utils/StringUtils.js +++ b/src/utils/StringUtils.js @@ -56,18 +56,30 @@ define(function (require, exports, module) { }); } + /** + * Regex escape + * + * @param {string} str + * @returns {string} + */ function regexEscape(str) { return str.replace(/([.?*+\^$\[\]\\(){}|\-])/g, "\\$1"); } - // Periods (aka "dots") are allowed in HTML identifiers, but jQuery interprets - // them as the start of a class selector, so they need to be escaped + /** + * Periods (aka "dots") are allowed in HTML identifiers, but jQuery interprets + * them as the start of a class selector, so they need to be escaped + * + * @param {string} str + * @returns {string} + */ function jQueryIdEscape(str) { return str.replace(/\./g, "\\."); } /** * Splits the text by new line characters and returns an array of lines + * * @param {string} text * @return {Array.} lines */ @@ -119,6 +131,7 @@ define(function (require, exports, module) { /** * Returns true if the given string starts with the given prefix. + * * @param {String} str * @param {String} prefix * @return {Boolean} @@ -137,6 +150,14 @@ define(function (require, exports, module) { return str.indexOf(suffix, str.length - suffix.length) !== -1; } + /** + * sort two urls alphabetically + * ensure folders appear before files on windows + * + * @param {string} a + * @param {string} b + * @returns {number} + */ function urlSort(a, b) { var a2, b2; function isFile(s) { @@ -161,6 +182,7 @@ define(function (require, exports, module) { /** * Return an escaped path or URL string that can be broken near path separators. + * * @param {string} url the path or URL to format * @return {string} the formatted path or URL */ @@ -207,6 +229,7 @@ define(function (require, exports, module) { /** * Truncate text to specified length. + * * @param {string} str Text to be truncated. * @param {number} len Length to which text should be truncated * @return {?string} Returns truncated text only if it was changed @@ -271,6 +294,12 @@ define(function (require, exports, module) { return randomId; } + /** + * Check if value is a valid number + * + * @param {string} value + * @returns {boolean} true if value is valid number, else false + */ function isNumber(value) { return parseFloat(value).toString() === value; } diff --git a/src/utils/TokenUtils.js b/src/utils/TokenUtils.js index a4bdf7cfc9..c111d31cfb 100644 --- a/src/utils/TokenUtils.js +++ b/src/utils/TokenUtils.js @@ -19,6 +19,8 @@ * */ +// @INCLUDE_IN_API_DOCS + /** * Functions for iterating through tokens in the current editor buffer. Useful for doing * light parsing that can rely purely on information gathered by the code coloring mechanism. @@ -40,8 +42,10 @@ define(function (require, exports, module) { } } - /* + /** * Caches the tokens for the given editor/line if needed + * + * @private * @param {!CodeMirror} cm * @param {!number} line * @return {Array.} (Cached) array of tokens @@ -64,8 +68,9 @@ define(function (require, exports, module) { return cache.tokens; } - /* + /** * Like cm.getTokenAt, but with caching. Way more performant for long lines. + * * @param {!CodeMirror} cm * @param {!{ch:number, line:number}} pos * @param {boolean} precise If given, results in more current results. Suppresses caching. @@ -82,7 +87,7 @@ define(function (require, exports, module) { return token || cm.getTokenAt(pos, precise); // fall back to CMs getTokenAt, for example in an empty line } - /** + /** * Creates a context object for the given editor and position, suitable for passing to the * move functions. * @param {!CodeMirror} cm @@ -167,7 +172,7 @@ define(function (require, exports, module) { return (ctx.pos.ch >= eol || ctx.token.end >= eol) && (ctx.pos.line >= ctx.editor.lineCount() - 1); } - /** + /** * Moves the given context in the given direction, skipping any whitespace it hits. * @param {function} moveFxn the function to move the context * @param {!{editor:!CodeMirror, pos:!{ch:number, line:number}, token:Object}} ctx @@ -203,7 +208,7 @@ define(function (require, exports, module) { * @param {!CodeMirror} cm CodeMirror instance * @param {!{line:number, ch:number}} pos Position to query for mode * @param {boolean} precise If given, results in more current results. Suppresses caching. - * @return {mode:{Object}, name:string} + * @return {{mode:{Object}, name:string}} */ function getModeAt(cm, pos, precise) { precise = precise || true; @@ -215,7 +220,7 @@ define(function (require, exports, module) { } name = (modeData.name === "xml") ? - modeData.configuration : modeData.name; + modeData.configuration : modeData.name; return {mode: modeData, name: name}; } diff --git a/src/utils/UrlParams.js b/src/utils/UrlParams.js index 7eef5b7e78..5a37af3a2b 100644 --- a/src/utils/UrlParams.js +++ b/src/utils/UrlParams.js @@ -19,6 +19,12 @@ * */ +/** + * This is deprecated; use browser APIs instead for working with URLs. + * + * @deprecated + */ + define(function (require, exports, module) { diff --git a/src/utils/ViewUtils.js b/src/utils/ViewUtils.js index 40433ba347..7e5f4ca589 100644 --- a/src/utils/ViewUtils.js +++ b/src/utils/ViewUtils.js @@ -37,6 +37,8 @@ define(function (require, exports, module) { /** * Positions shadow background elements to indicate vertical scrolling. + * + * @private * @param {!DOMElement} $displayElement the DOMElement that displays the shadow * @param {!Object} $scrollElement the object that is scrolled * @param {!DOMElement} $shadowTop div .scroller-shadow.top @@ -226,7 +228,7 @@ define(function (require, exports, module) { if (selectionExtensionTop < scrollerTop || selectionExtensionBottom > scrollerBottom) { $selectionExtension.css("clip", "rect(" + Math.max(scrollerTop - selectionExtensionTop - selectionExtensionClipOffsetYBy, 0) + "px, auto, " + - (selectionExtensionHeight - Math.max(selectionExtensionBottom - scrollerBottom, 0)) + "px, auto)"); + (selectionExtensionHeight - Math.max(selectionExtensionBottom - scrollerBottom, 0)) + "px, auto)"); } else { $selectionExtension.css("clip", ""); } @@ -501,6 +503,9 @@ define(function (require, exports, module) { return null; } + /** + * Hides the main toolbar + */ function hideMainToolBar() { $("#main-toolbar").addClass("forced-hidden"); $(".main-view .content").each(function (index, element) { @@ -508,6 +513,9 @@ define(function (require, exports, module) { }); } + /** + * Shows the main toolbar + */ function showMainToolBar() { $("#main-toolbar").removeClass("forced-hidden"); $(".main-view .content").each(function (index, element) {