Skip to content

Commit

Permalink
docs: refine API docs for files in Search dir
Browse files Browse the repository at this point in the history
  • Loading branch information
@devvaannsh
devvaannsh committed Oct 27, 2024
1 parent 085a4a4 commit 24a367b
Show file tree
Hide file tree
Showing 20 changed files with 397 additions and 845 deletions.
41 changes: 27 additions & 14 deletions docs/API-Reference/search/FileFilters.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,31 +3,38 @@
const FileFilters = brackets.getModule("search/FileFilters")
```

<a name="_picker"></a>

## \_picker : [<code>DropdownButton</code>](#DropdownButton)
**Kind**: global variable
<a name="$filterContainer"></a>

## $filterContainer : <code>jQuery</code>
**Kind**: global variable
<a name="DropdownButton"></a>

## DropdownButton
Utilities for managing file-set filters, as used in Find in Files.Includes both UI for selecting/editing filters, as well as the actual file-filtering implementation.
Utilities for managing file-set filters, as used in Find in Files.
Includes both UI for selecting/editing filters, as well as the actual file-filtering implementation.

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

## FILTER\_TYPE\_EXCLUDE : <code>string</code>
**Kind**: global constant
<a name="FILTER_TYPE_INCLUDE"></a>

## FILTER\_TYPE\_INCLUDE : <code>string</code>
**Kind**: global constant
<a name="FILTER_TYPE_NO_FILTER"></a>

## FILTER\_TYPE\_NO\_FILTER : <code>string</code>
**Kind**: global constant
<a name="getActiveFilter"></a>

## getActiveFilter() ⇒ <code>Object</code>
A search filter is an array of one or more glob strings. The filter must be 'compiled' via compile()before passing to filterPath()/filterFileList().
A search filter is an array of one or more glob strings. The filter must be 'compiled' via compile()
before passing to filterPath()/filterFileList().

**Kind**: global function
**Returns**: <code>Object</code> - a globeFilter filter that can be passed to filterPath()/filterFileList().
<a name="setActiveFilter"></a>

## setActiveFilter(filter, [filterType])
Sets and save the index of the active filter. Automatically set when editFilter() is completed.If no filter is passed in, then clear the last active filter index by setting it to -1.
Sets and save the index of the active filter. Automatically set when editFilter() is completed.
If no filter is passed in, then clear the last active filter index by setting it to -1.

**Kind**: global function

Expand All @@ -39,7 +46,8 @@ Sets and save the index of the active filter. Automatically set when editFilter(
<a name="compile"></a>

## compile(userFilterString) ⇒ <code>Object</code>
Converts a user-specified filter object (as chosen in picker or retrieved from getFilters()) to a 'compiled' formthat can be used with filterPath()/filterFileList().
Converts a user-specified filter object (as chosen in picker or retrieved from getFilters()) to a 'compiled' form
that can be used with filterPath()/filterFileList().

**Kind**: global function
**Returns**: <code>Object</code> - a globeFilter filter that can be passed to filterPath()/filterFileList().
Expand All @@ -51,7 +59,9 @@ Converts a user-specified filter object (as chosen in picker or retrieved from g
<a name="filterPath"></a>

## filterPath(compiledFilter, fullPath) ⇒ <code>boolean</code>
Returns false if the given path matches any of the exclusion globs in the given filter. Returns trueif the path does not match any of the globs. If filtering many paths at once, use filterFileList()for much better performance.
Returns false if the given path matches any of the exclusion globs in the given filter. Returns true
if the path does not match any of the globs. If filtering many paths at once, use filterFileList()
for much better performance.

**Kind**: global function

Expand Down Expand Up @@ -87,7 +97,10 @@ Returns a copy of 'file path' strings that match any of the exclusion globs in t
<a name="createFilterPicker"></a>

## createFilterPicker() ⇒ <code>jQueryObject</code>
Creates a UI element for selecting a filter. The picker is populated with a list of recently used filters,an option to edit the selected filter, and another option to create a new filter. The client should call`commitDropdown()` when the UI containing the filter picker is confirmed, which updates the Most Recently Used (MRU) order, and then use the returned filter object as needed.
Creates a UI element for selecting a filter. The picker is populated with a list of recently used filters,
an option to edit the selected filter, and another option to create a new filter. The client should call
`commitDropdown()` when the UI containing the filter picker is confirmed, which updates the Most Recently
Used (MRU) order, and then use the returned filter object as needed.

**Kind**: global function
**Returns**: <code>jQueryObject</code> - The Picker UI as a jQuery object.
Expand Down
80 changes: 41 additions & 39 deletions docs/API-Reference/search/FindBar.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,32 +10,42 @@ const FindBar = brackets.getModule("search/FindBar")

* [FindBar](#FindBar)
* [new FindBar([scopeLabel])](#new_FindBar_new)
* _instance_
* [.open()](#FindBar+open)
* [.close(suppressAnimation)](#FindBar+close)
* [.isClosed()](#FindBar+isClosed) ⇒ <code>boolean</code>
* [.getOptions()](#FindBar+getOptions) ⇒ <code>Object</code>
* [.getQueryInfo()](#FindBar+getQueryInfo) ⇒ <code>Object</code>
* [.showError(error, [isHTML], [isFilterError])](#FindBar+showError)
* [.showFindCount(count)](#FindBar+showFindCount)
* [.showNoResults(showIndicator, showMessage)](#FindBar+showNoResults)
* [.getReplaceText()](#FindBar+getReplaceText) ⇒ <code>string</code>
* [.enable(enable)](#FindBar+enable)
* [.isEnabled()](#FindBar+isEnabled) ⇒ <code>boolean</code>
* [.isReplaceEnabled()](#FindBar+isReplaceEnabled) ⇒ <code>boolean</code>
* [.enableNavigation(enable)](#FindBar+enableNavigation)
* [.enableReplace(enable)](#FindBar+enableReplace)
* [.focusQuery()](#FindBar+focusQuery)
* [.focusReplace()](#FindBar+focusReplace)
* [.showIndexingSpinner()](#FindBar+showIndexingSpinner)
* [.redoInstantSearch()](#FindBar+redoInstantSearch)
* _static_
* [.getInitialQuery(currentFindBar, activeEditor)](#FindBar.getInitialQuery) ⇒ <code>Object</code>
* [.open()](#FindBar+open)
* [.close(suppressAnimation)](#FindBar+close)
* [.isClosed()](#FindBar+isClosed) ⇒ <code>boolean</code>
* [.getOptions()](#FindBar+getOptions) ⇒ <code>Object</code>
* [.getQueryInfo()](#FindBar+getQueryInfo) ⇒ <code>Object</code>
* [.showError(error, [isHTML], [isFilterError])](#FindBar+showError)
* [.showFindCount(count)](#FindBar+showFindCount)
* [.showNoResults(showIndicator, showMessage)](#FindBar+showNoResults)
* [.getReplaceText()](#FindBar+getReplaceText) ⇒ <code>string</code>
* [.enable(enable)](#FindBar+enable)
* [.isEnabled()](#FindBar+isEnabled) ⇒ <code>boolean</code>
* [.isReplaceEnabled()](#FindBar+isReplaceEnabled) ⇒ <code>boolean</code>
* [.enableNavigation(enable)](#FindBar+enableNavigation)
* [.enableReplace(enable)](#FindBar+enableReplace)
* [.focusQuery()](#FindBar+focusQuery)
* [.focusReplace()](#FindBar+focusReplace)
* [.showIndexingSpinner()](#FindBar+showIndexingSpinner)
* [.redoInstantSearch()](#FindBar+redoInstantSearch)

<a name="new_FindBar_new"></a>

### new FindBar([scopeLabel])
Find Bar UI component, used for both single- and multi-file find/replace. This doesn't actuallycreate and add the FindBar to the DOM - for that, call open().Dispatches these events:- queryChange - when the user types in the input field or sets a query option. Use getQueryInfo() to get the current query state.- doFind - when the user chooses to do a Find Previous or Find Next. Parameters are: shiftKey - boolean, false for Find Next, true for Find Previous- doReplace - when the user chooses to do a single replace. Use getReplaceText() to get the current replacement text.- doReplaceBatch - when the user chooses to initiate a Replace All. Use getReplaceText() to get the current replacement text.- doReplaceAll - when the user chooses to perform a Replace All. Use getReplaceText() to get the current replacement text.- close - when the find bar is closed
Find Bar UI component, used for both single- and multi-file find/replace. This doesn't actually
create and add the FindBar to the DOM - for that, call open().

Dispatches these events:

- queryChange - when the user types in the input field or sets a query option. Use getQueryInfo()
to get the current query state.
- doFind - when the user chooses to do a Find Previous or Find Next.
Parameters are:
shiftKey - boolean, false for Find Next, true for Find Previous
- doReplace - when the user chooses to do a single replace. Use getReplaceText() to get the current replacement text.
- doReplaceBatch - when the user chooses to initiate a Replace All. Use getReplaceText() to get the current replacement text.
- doReplaceAll - when the user chooses to perform a Replace All. Use getReplaceText() to get the current replacement text.
- close - when the find bar is closed


| Param | Type | Description |
Expand Down Expand Up @@ -106,7 +116,8 @@ Set the find count.
<a name="FindBar+showNoResults"></a>

### findBar.showNoResults(showIndicator, showMessage)
Show or hide the no-results indicator and optional message. This is also used toindicate regular expression errors.
Show or hide the no-results indicator and optional message. This is also used to
indicate regular expression errors.

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

Expand All @@ -124,7 +135,9 @@ Returns the current replace text.
<a name="FindBar+enable"></a>

### findBar.enable(enable)
Enables or disables the controls in the Find bar. Note that if enable is true, *all* controls will bere-enabled, even if some were previously disabled using enableNavigation() or enableReplace(), so youwill need to refresh their enable state after calling this.
Enables or disables the controls in the Find bar. Note that if enable is true, *all* controls will be
re-enabled, even if some were previously disabled using enableNavigation() or enableReplace(), so you
will need to refresh their enable state after calling this.

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

Expand All @@ -145,7 +158,8 @@ Enables or disables the controls in the Find bar. Note that if enable is true, *
<a name="FindBar+enableNavigation"></a>

### findBar.enableNavigation(enable)
Enable or disable the navigation controls if present. Note that if the Find bar is currently disabled(i.e. isEnabled() returns false), this will have no effect.
Enable or disable the navigation controls if present. Note that if the Find bar is currently disabled
(i.e. isEnabled() returns false), this will have no effect.

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

Expand All @@ -156,7 +170,8 @@ Enable or disable the navigation controls if present. Note that if the Find bar
<a name="FindBar+enableReplace"></a>

### findBar.enableReplace(enable)
Enable or disable the replace controls if present. Note that if the Find bar is currently disabled(i.e. isEnabled() returns false), this will have no effect.
Enable or disable the replace controls if present. Note that if the Find bar is currently disabled
(i.e. isEnabled() returns false), this will have no effect.

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

Expand Down Expand Up @@ -188,16 +203,3 @@ The indexing spinner is usually shown when node is indexing files
Force a search again

**Kind**: instance method of [<code>FindBar</code>](#FindBar)
<a name="FindBar.getInitialQuery"></a>

### FindBar.getInitialQuery(currentFindBar, activeEditor) ⇒ <code>Object</code>
Retrieves the appropriate query and replacement text to prepopulate the Find Bar.

**Kind**: static method of [<code>FindBar</code>](#FindBar)
**Returns**: <code>Object</code> - An object containing the query and replacement text to prepopulate the Find Bar.

| Param | Type | Description |
| --- | --- | --- |
| currentFindBar | [<code>FindBar</code>](#FindBar) | The currently open Find Bar, if any. |
| activeEditor | <code>Editor</code> | The active editor, if any. |

128 changes: 14 additions & 114 deletions docs/API-Reference/search/FindInFiles.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,77 +8,18 @@ const FindInFiles = brackets.getModule("search/FindInFiles")
## searchModel : <code>SearchModel</code>
The search query and results model.

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

## \_cachedFileSystemEvents
This stores file system events emitted by watchers that were not yet processed

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

## \_processCachedFileSystemEvents
Debounced function to process emitted file system eventsfor cases when there's a lot of fs events emitted in a very short period of time

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

## @type : <code>Object</code>
Token used to indicate a specific reason for zero search results

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

## MAX\_DISPLAY\_LENGTH
Maximum length of text displayed in search results panel

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

## FILE\_SYSTEM\_EVENT\_DEBOUNCE\_TIME
Waits for FS changes to stack up until processing them(scripts like npm install can do a lot of movements on the disk)

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

## \_removeListeners()
Remove the listeners that were tracking potential search result changes

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

## \_addListeners()
Add listeners to track events that might change the search result set

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

## \_subtreeFilter(file, scope) ⇒ <code>boolean</code>
Checks that the file matches the given subtree scope. To fully check whether the fileshould be in the search set, use _inSearchScope() instead - a supserset of this.

**Kind**: global function

| Param | Type | Description |
| --- | --- | --- |
| file | <code>File</code> | |
| scope | <code>FileSystemEntry</code> | Search scope, or null if whole project |

<a name="_isReadableFileType"></a>

## \_isReadableFileType(fullPath) ⇒ <code>boolean</code>
Filters out files that are known binary types.

**Kind**: global function
**Returns**: <code>boolean</code> - True if the file's contents can be read as text

| Param | Type |
| --- | --- |
| fullPath | <code>string</code> |

<a name="getCandidateFiles"></a>

## getCandidateFiles(scope) ⇒ <code>$.Promise</code>
Finds all candidate files to search in the given scope's subtree that are not binary content. Does NOT applythe current filter yet.
Finds all candidate files to search in the given scope's subtree that are not binary content. Does NOT apply
the current filter yet.

**Kind**: global function
**Returns**: <code>$.Promise</code> - A promise that will be resolved with the list of files in the scope. Never rejected.
Expand All @@ -87,21 +28,12 @@ Finds all candidate files to search in the given scope's subtree that are not bi
| --- | --- | --- |
| scope | <code>FileSystemEntry</code> | Search scope, or null if whole project |

<a name="_inSearchScope"></a>

## \_inSearchScope(file) ⇒ <code>boolean</code>
Checks that the file is eligible for inclusion in the search (matches the user's subtree scope andfile exclusion filters, and isn't binary). Used when updating results incrementally - during theinitial search, these checks are done in bulk via getCandidateFiles() and the filterFileList() callafter it.

**Kind**: global function

| Param | Type |
| --- | --- |
| file | <code>File</code> |

<a name="doSearchInScope"></a>

## doSearchInScope(queryInfo, scope, filter, replaceText, candidateFilesPromise) ⇒ <code>$.Promise</code>
Does a search in the given scope with the given filter. Used when you want to start a searchprogrammatically. Make sure that project indexing is complete by calling isProjectIndexingComplete()Else, an empty result will be returned if search is invoked before any files are indexed.
Does a search in the given scope with the given filter. Used when you want to start a search
programmatically. Make sure that project indexing is complete by calling isProjectIndexingComplete()
Else, an empty result will be returned if search is invoked before any files are indexed.

**Kind**: global function
**Returns**: <code>$.Promise</code> - A promise that's resolved with the search results or rejected when the find competes.
Expand All @@ -120,7 +52,8 @@ Does a search in the given scope with the given filter. Used when you want to st
Replaces a set of search results with the specified `replaceText`, either on disk or in memory.

**Kind**: global function
**Returns**: <code>$.Promise</code> - A promise that resolves when the replacement is finished or is rejected with an array of errors if any occur. Each item in the array will be an object containing:
**Returns**: <code>$.Promise</code> - A promise that resolves when the replacement is finished or is rejected with an array of errors if any occur.
Each item in the array will be an object containing:

| Param | Type | Description |
| --- | --- | --- |
Expand All @@ -132,50 +65,17 @@ Replaces a set of search results with the specified `replaceText`, either on dis
| item | <code>string</code> | The full path to the file that could not be updated. |
| error | <code>string</code> | Either a FileSystem error or one of the `FindInFiles.ERROR_*` constants. |

<a name="_searchcollapseResults"></a>

## \_searchcollapseResults()
Notify worker that the results should be collapsed

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

## filesChanged(fileList)
Inform worker that the list of files has changed.

**Kind**: global function

| Param | Type | Description |
| --- | --- | --- |
| fileList | <code>array</code> | The list of files that changed. |

<a name="filesRemoved"></a>

## filesRemoved(fileList)
Inform worker that the list of files have been removed.

**Kind**: global function

| Param | Type | Description |
| --- | --- | --- |
| fileList | <code>array</code> | The list of files that was removed. |

<a name="_debouncedFileSystemChangeHandler"></a>

## \_debouncedFileSystemChangeHandler()
Wrapper function for _fileSystemChangeHandler which handles all incoming fs eventsputting them to cache and executing a debounced function

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

## \_initCache()
On project change, inform worker about the new list of files that needs to be crawled.Instant search is also disabled for the time being till the crawl is complete in worker.This should never be called directly and only called via _scheduleCacheInit() belowto not affect project load performance.

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

## getNextPageofSearchResults() ⇒ <code>object</code>
Gets the next page of search results to append to the result set.

**Kind**: global function
**Returns**: <code>object</code> - A promise that's resolved with the search results or rejected when the find competes.
<a name="getAllSearchResults"></a>

## getAllSearchResults() ⇒ <code>object</code>
Get all the search results.

**Kind**: global function
**Returns**: <code>object</code> - A promise that's resolved with the search results or rejected when the find competes.
Loading

0 comments on commit 24a367b

Please sign in to comment.