Skip to content

Commit

Permalink
docs: refine API docs for files in View dir
Browse files Browse the repository at this point in the history
  • Loading branch information
@devvaannsh
devvaannsh committed Oct 28, 2024
1 parent 085a4a4 commit 746e8e2
Show file tree
Hide file tree
Showing 8 changed files with 377 additions and 332 deletions.
212 changes: 90 additions & 122 deletions docs/API-Reference/view/MainViewManager.md
View file

Large diffs are not rendered by default.

249 changes: 150 additions & 99 deletions docs/API-Reference/view/Pane.md
View file

Large diffs are not rendered by default.

22 changes: 9 additions & 13 deletions docs/API-Reference/view/ViewStateManager.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,15 @@ const ViewStateManager = brackets.getModule("view/ViewStateManager")
<a name="_"></a>

## \_
ViewStateManager is a singleton for views to park their global viwe state. The state is savedwith project data but the View or View Factory is responsible for restoring the view statewhen the view is created.Views should implement `getViewState()` so that the view state can be saved and that data is cachedfor later use.Views or View Factories are responsible for restoring the view state when the view of that file is createdby recalling the cached state. Views determine what data is store in the view state and how to restore it.
ViewStateManager is a singleton for views to park their global viwe state. The state is saved
with project data but the View or View Factory is responsible for restoring the view state
when the view is created.

Views should implement `getViewState()` so that the view state can be saved and that data is cached
for later use.

Views or View Factories are responsible for restoring the view state when the view of that file is created
by recalling the cached state. Views determine what data is store in the view state and how to restore it.

**Kind**: global variable
<a name="reset"></a>
Expand All @@ -15,18 +23,6 @@ ViewStateManager is a singleton for views to park their global viwe state. The s
resets the view state cache

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

## \_setViewState(file, viewState)
Sets the view state for the specfied file

**Kind**: global function

| Param | Type | Description |
| --- | --- | --- |
| file | <code>File</code> | the file to record the view state for |
| viewState | <code>\*</code> | any data that the view needs to restore the view state. |

<a name="updateViewState"></a>

## updateViewState(view, viewState)
Expand Down
122 changes: 42 additions & 80 deletions docs/API-Reference/view/WorkspaceManager.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,98 +3,43 @@
const WorkspaceManager = brackets.getModule("view/WorkspaceManager")
```

<a name="$windowContent"></a>

## $windowContent : <code>jQueryObject</code>
The ".content" vertical stack (editor + all header/footer panels)

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

## $editorHolder : <code>jQueryObject</code>
The "#editor-holder": has only one visible child, the current CodeMirror instance (or the no-editor placeholder)

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

## $mainToolbar : <code>jQueryObject</code>
The "#main-toolbay": to the right side holding plugin panels and icons

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

## $mainPluginPanel : <code>jQueryObject</code>
The "#main-plugin-panel": The plugin panel main container

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

## $pluginIconsBar : <code>jQueryObject</code>
The "#plugin-icons-bar": holding all the plugin icons

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

## panelIDMap
A map from panel ID's to all reated panels

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

## windowResizing : <code>boolean</code>
Have we already started listening for the end of the ongoing window resize?

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

## AppInit
Manages layout of panels surrounding the editor area, and size of the editor area (but not its contents).Updates panel sizes when the window is resized. Maintains the max resizing limits for panels, based oncurrently available window size.Events:`workspaceUpdateLayout` When workspace size changes for any reason (including panel show/hide panel resize, or the window resize). The 2nd arg is the available workspace height. The 3rd arg is a refreshHint flag for internal use (passed in to recomputeLayout)

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

## calcAvailableHeight() ⇒ <code>number</code>
Calculates the available height for the full-size Editor (or the no-editor placeholder),accounting for the current size of all visible panels, toolbar, & status bar.
Manages layout of panels surrounding the editor area, and size of the editor area (but not its contents).

**Kind**: global function
<a name="updateResizeLimits"></a>
Updates panel sizes when the window is resized. Maintains the max resizing limits for panels, based on
currently available window size.

## updateResizeLimits()
Updates panel resize limits to disallow making panels big enough to shrink editor area below 0

**Kind**: global function
<a name="triggerUpdateLayout"></a>
Events:
`workspaceUpdateLayout` When workspace size changes for any reason (including panel show/hide panel resize, or the window resize).
The 2nd arg is the available workspace height.
The 3rd arg is a refreshHint flag for internal use (passed in to recomputeLayout)

## triggerUpdateLayout([refreshHint])
Calculates a new size for editor-holder and resizes it accordingly, then and dispatches the "workspaceUpdateLayout"event. (The editors within are resized by EditorManager, in response to that event).

**Kind**: global function

| Param | Type | Description |
| --- | --- | --- |
| [refreshHint] | <code>boolean</code> | true to force a complete refresh |

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

## handleWindowResize()
Trigger editor area resize whenever the window is resized
## EVENT\_WORKSPACE\_UPDATE\_LAYOUT
Event triggered when the workspace layout updates.

**Kind**: global function
<a name="listenToResize"></a>
**Kind**: global constant
<a name="EVENT_WORKSPACE_PANEL_SHOWN"></a>

## listenToResize($panel)
Trigger editor area resize whenever the given panel is shown/hidden/resized
## EVENT\_WORKSPACE\_PANEL\_SHOWN
Event triggered when a panel is shown.

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

| Param | Type | Description |
| --- | --- | --- |
| $panel | <code>jQueryObject</code> | the jquery object in which to attach event handlers |
## EVENT\_WORKSPACE\_PANEL\_HIDDEN
Event triggered when a panel is hidden.

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

## createBottomPanel(id, $panel, [minSize]) ⇒ <code>Panel</code>
Creates a new resizable panel beneath the editor area and above the status bar footer. Panel is initially invisible.The panel's size & visibility are automatically saved & restored as a view-state preference.
Creates a new resizable panel beneath the editor area and above the status bar footer. Panel is initially invisible.
The panel's size & visibility are automatically saved & restored as a view-state preference.

**Kind**: global function

Expand All @@ -107,7 +52,9 @@ Creates a new resizable panel beneath the editor area and above the status bar f
<a name="createPluginPanel"></a>

## createPluginPanel(id, $panel, [minSize], $toolbarIcon, [initialSize]) ⇒ <code>Panel</code>
Creates a new resizable plugin panel associated with the given toolbar icon. Panel is initially invisible.The panel's size & visibility are automatically saved & restored. Only one panel can be associated with atoolbar icon.
Creates a new resizable plugin panel associated with the given toolbar icon. Panel is initially invisible.
The panel's size & visibility are automatically saved & restored. Only one panel can be associated with a
toolbar icon.

**Kind**: global function

Expand Down Expand Up @@ -141,18 +88,33 @@ Gets the Panel interface for the given ID. Can return undefined if no panel with
<a name="recomputeLayout"></a>

## recomputeLayout(refreshHint)
Called when an external widget has appeared and needs some of the space occupied by the mainview manager
Called when an external widget has appeared and needs some of the space occupied
by the mainview manager

**Kind**: global function

| Param | Type | Description |
| --- | --- | --- |
| refreshHint | <code>boolean</code> | true to refresh the editor, false if not |

<a name="isPanelVisible"></a>

## isPanelVisible(panelID) ⇒ <code>boolean</code>
Responsible to check if the panel is visible or not.
Returns true if visible else false.

**Kind**: global function

| Param |
| --- |
| panelID |

<a name="addEscapeKeyEventHandler"></a>

## addEscapeKeyEventHandler(consumerName, eventHandler) ⇒ <code>boolean</code>
If any widgets related to the editor needs to handle the escape key event, add it here. returning true from theregistered handler will prevent primary escape key toggle panel behavior of phoenix. Note that returning truewill no stop the event bubbling, that has to be controlled with the event parameter forwarded to the handler.
If any widgets related to the editor needs to handle the escape key event, add it here. returning true from the
registered handler will prevent primary escape key toggle panel behavior of phoenix. Note that returning true
will no stop the event bubbling, that has to be controlled with the event parameter forwarded to the handler.

**Kind**: global function
**Returns**: <code>boolean</code> - true if added
Expand Down
24 changes: 19 additions & 5 deletions src/view/MainViewManager.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,11 @@ define(function (require, exports, module) {
Pane = require("view/Pane").Pane,
KeyBindingManager = brackets.getModule("command/KeyBindingManager");

/**
* Event current file change
* @const
* @type {string}
*/
const EVENT_CURRENT_FILE_CHANGE = "currentFileChange";

/**
Expand Down Expand Up @@ -220,6 +225,7 @@ define(function (require, exports, module) {
/**
* The global MRU list (for traversing)
* @type {Array.<file:File, paneId:string>}
* @private
*/
var _mruList = [];

Expand Down Expand Up @@ -293,6 +299,7 @@ define(function (require, exports, module) {
* Resolve paneId to actual pane.
* @param {?string} paneId - id of the desired pane. May be symbolic or null (to indicate current pane)
* @return {string} id of the pane in which to open the document
* @private
*/
function _resolvePaneId(paneId) {
if (!paneId || paneId === ACTIVE_PANE) {
Expand Down Expand Up @@ -329,6 +336,7 @@ define(function (require, exports, module) {
* Determines if the pane id is a special pane id
* @param {!string} paneId - the id to test
* @return {boolean} true if the pane id is a special identifier, false if not
* @private
*/
function _isSpecialPaneId(paneId) {
return paneId === ACTIVE_PANE || paneId === ALL_PANES;
Expand Down Expand Up @@ -409,6 +417,7 @@ define(function (require, exports, module) {

/**
* Retrieves the Pane ID for the specified container
* @private
* @param {!jQuery} $el - the element of the pane to fetch
* @return {?string} the id of the pane that matches the container or undefined if a pane doesn't exist for that container
*/
Expand Down Expand Up @@ -1153,6 +1162,7 @@ define(function (require, exports, module) {

/**
* Updates the header text for all panes
* @private
*/
function _updatePaneHeaders() {
_forEachPaneOrPanes(ALL_PANES, function (pane) {
Expand Down Expand Up @@ -1291,6 +1301,7 @@ define(function (require, exports, module) {
/**
* Opens a file in the specified pane this can be used to open a file with a custom viewer
* or a document for editing. If it's a document for editing, edit is called on the document
* @private
* @param {!string} paneId - id of the pane in which to open the document
* @param {!File} file - file to open
* @param {{noPaneActivate:boolean=}=} optionsIn - options
Expand Down Expand Up @@ -1416,7 +1427,7 @@ define(function (require, exports, module) {

/**
* Closes a file in the specified pane or panes.
*
* @private
* @param {!string} paneId - The ID of the pane in which to close the document.
* @param {!File} file - The file to close.
* @param {Object} [optionsIn] - Optional parameters for the close operation.
Expand All @@ -1437,6 +1448,7 @@ define(function (require, exports, module) {

/**
* Closes a list of file in the specified pane or panes
* @private
* @param {!string} paneId - id of the pane in which to open the document
* @param {!Array.<File>} fileList - files to close
* This function does not fail if the file is not open
Expand All @@ -1454,6 +1466,7 @@ define(function (require, exports, module) {

/**
* Closes all files in the specified pane or panes
* @private
* @param {!string} paneId - id of the pane in which to open the document
* This function does not fail if the file is not open
*/
Expand Down Expand Up @@ -1493,7 +1506,8 @@ define(function (require, exports, module) {

/**
* Destroys an editor object if a document is no longer referenced
* @param {!Document} doc - document to destroy
* @private
* @param {!Document} document - document to destroy
*/
function _destroyEditorIfNotNeeded(document) {
if (!(document instanceof DocumentManager.Document)) {
Expand All @@ -1518,7 +1532,7 @@ define(function (require, exports, module) {


/**
* Loads the workingset state
* Loads the working set state
* @private
*/
function _loadViewState(e) {
Expand All @@ -1543,7 +1557,7 @@ define(function (require, exports, module) {
}
};

// Add all files to the workingset without verifying that
// Add all files to the working set without verifying that
// they still exist on disk (for faster project switching)
files.forEach(function (value) {
result.panes[FIRST_PANE].push(value);
Expand Down Expand Up @@ -1633,7 +1647,7 @@ define(function (require, exports, module) {
}

/**
* Saves the workingset state
* Saves the working set state
* @private
*/
function _saveViewState() {
Expand Down
Loading

0 comments on commit 746e8e2

Please sign in to comment.