mirror of
https://github.com/pulsar-edit/pulsar.git
synced 2024-09-11 19:17:09 +03:00
parent
7d28d50993
commit
519916272d
@ -3,27 +3,25 @@ const { Disposable } = require('event-kit');
|
||||
|
||||
const AnyConstructor = Symbol('any-constructor');
|
||||
|
||||
/**
|
||||
* Essential: `ViewRegistry` handles the association between model and view
|
||||
* types in Pulsar. We call this association a View Provider. As in, for a given
|
||||
* model, this class can provide a view via {::getView}, as long as the
|
||||
* model/view association was registered via {::addViewProvider}.
|
||||
*
|
||||
* If you're adding your own kind of pane item, a good strategy for all but the
|
||||
* simplest items is to separate the model and the view. THe model handles
|
||||
* application logic and is the primary point of the API interaction. The view
|
||||
* just handles presentation.
|
||||
|
||||
* Note: Modles can be any object, but must implement a `getTtile()` function
|
||||
* if they are to be displayed in a {Pane}.
|
||||
*
|
||||
* View providers inform the workspace how your model objects should be
|
||||
* presented in the DOM. A view provider must always return a DOM node, which
|
||||
* makes [HTML 5 custom elements](http://www.html5rocks.com/en/tutorials/webcomponents/customelements/)
|
||||
* an ideal tool for implementing views in Pulsar.
|
||||
*
|
||||
* You can access the `ViewRegistry` object via `atom.views`
|
||||
*/
|
||||
// Essential: `ViewRegistry` handles the association between model and view
|
||||
// types in Pulsar. We call this association a View Provider. As in, for a given
|
||||
// model, this class can provide a view via {::getView}, as long as the
|
||||
// model/view association was registered via {::addViewProvider}
|
||||
//
|
||||
// If you're adding your own kind of pane item, a good strategy for all but the
|
||||
// simplest items is to separate the model and the view. The model handles
|
||||
// application logic and is the primary point of API interaction. The view
|
||||
// just handles presentation.
|
||||
//
|
||||
// Note: Models can be any object, but must implement a `getTitle()` function
|
||||
// if they are to be displayed in a {Pane}
|
||||
//
|
||||
// View providers inform the workspace how your model objects should be
|
||||
// presented in the DOM. A view provider must always return a DOM node, which
|
||||
// makes [HTML 5 custom elements](http://www.html5rocks.com/en/tutorials/webcomponents/customelements/)
|
||||
// an ideal tool for implementing views in Pulsar.
|
||||
//
|
||||
// You can access the `ViewRegistry` object via `atom.views`.
|
||||
module.exports = class ViewRegistry {
|
||||
constructor(atomEnvironment) {
|
||||
this.animationFrameRequest = null;
|
||||
@ -39,30 +37,34 @@ module.exports = class ViewRegistry {
|
||||
this.clearDocumentRequests();
|
||||
}
|
||||
|
||||
/**
|
||||
* Essential: Add a provider that will be used to construct views in the
|
||||
* workspace's view layer based on model objects in its model layer.
|
||||
*
|
||||
* Text editors are divided into a model and a view layer, so when you interact
|
||||
* with methods like `atom.workspace.getActiveTextEditor()` you're only going
|
||||
* to get the model object. We display text editors on screen by teaching the
|
||||
* workspace what view constructor it should use to represent them
|
||||
* @example
|
||||
* atom.views.addViewProvider TextEditor, (textEditor) ->
|
||||
* textEditorElement = new TextEditorElement
|
||||
* textEditorElement.initialize(textEditor)
|
||||
* textEditorElement
|
||||
* @param {function} [modelConstructor] - Constructor Function for you model.
|
||||
* If a constructor is given, the `createView` function will only be used for
|
||||
* model objects inheriting from that constructor. Otherwise, it will
|
||||
* will be called for any object.
|
||||
* @param {function} createView - Factory function that is not passed an
|
||||
* instance of your model and must return a subclass of `HTMLElement` or
|
||||
* `undefined`. If it returns `undefined`, then the registry will continue to
|
||||
* search for other viewproviders.
|
||||
* returns {Disposable} Returns a `Disposable` on which `.dispose()` can be
|
||||
* called to added provider.
|
||||
*/
|
||||
// Essential: Add a provider that will be used to construct views in the
|
||||
// workspace's view layer based on model objects in its model layer.
|
||||
//
|
||||
// ## Examples
|
||||
//
|
||||
// Text editors are divided into a model and a view layer, so when you interact
|
||||
// with methods like `atom.workspace.getActiveTextEditor()` you're only going
|
||||
// to get the model object. We display text editors on screen by teaching the
|
||||
// workspace what view constructor it should use to represent them:
|
||||
//
|
||||
// ```coffee
|
||||
// atom.views.addViewProvider TextEditor, (textEditor) ->
|
||||
// textEditorElement = new TextEditorElement
|
||||
// textEditorElement.initialize(textEditor)
|
||||
// textEditorElement
|
||||
// ```
|
||||
//
|
||||
// * `modelConstructor` (optional) Constructor {Function} for your model. If
|
||||
// a constructor is given, the `createView` function will only be used
|
||||
// for model objects inheriting from that constructor. Otherwise, it will
|
||||
// will be called for any object.
|
||||
// * `createView` Factory {Function} that is passed an instance of your model
|
||||
// and must return a subclass of `HTMLElement` or `undefined`. If it returns
|
||||
// `undefined`, then the registry will continue to search for other view
|
||||
// providers.
|
||||
//
|
||||
// Returns a {Disposable} on which `.dispose()` can be called to remove the
|
||||
// added provider.
|
||||
addViewProvider(modelConstructor, createView) {
|
||||
let provider;
|
||||
if (arguments.length === 1) {
|
||||
@ -96,28 +98,31 @@ module.exports = class ViewRegistry {
|
||||
return this.providers.length;
|
||||
}
|
||||
|
||||
/**
|
||||
* Essential: Get the view associated with an object in the workspace.
|
||||
*
|
||||
* If you're just *using* the workspace, you shouldn't need to access the view
|
||||
* layer, but view layer access may be necessary if you want to perform DOM
|
||||
* manipulation that isn't supported via the model API.
|
||||
* ## View Resolution Algorithm
|
||||
* The view associated with the object is resolved using the following sequence
|
||||
* 1. Is the object an instance of `HTMLEelement`? If true, return the object.
|
||||
* 2. Does the object have a method named `getElement` that returns an instance
|
||||
* of `HTMLElement`? If true, return that value.
|
||||
* 3. Does the object have a property named `element` with a value which is
|
||||
* an instance of `HTMLElement`? If true, return the property value.
|
||||
* 4. Is the object a jQuery object, indicated by the presence of a `jquery`
|
||||
* property? If true, return the root DOM element (i.e. `object[0]`).
|
||||
* 5. Has a view provider been registered for the object? If true, use the
|
||||
* provider to create a view associated with the subject, and return
|
||||
* the view.
|
||||
*
|
||||
* If no associated view is returned by the sequence an error is thrown.
|
||||
* @returns {object} A DOM element.
|
||||
*/
|
||||
// Essential: Get the view associated with an object in the workspace.
|
||||
//
|
||||
// If you're just *using* the workspace, you shouldn't need to access the view
|
||||
// layer, but view layer access may be necessary if you want to perform DOM
|
||||
// manipulation that isn't supported via the model API.
|
||||
//
|
||||
// ## View Resolution Algorithm
|
||||
//
|
||||
// The view associated with the object is resolved using the following
|
||||
// sequence
|
||||
//
|
||||
// 1. Is the object an instance of `HTMLElement`? If true, return the object.
|
||||
// 2. Does the object have a method named `getElement` that returns an
|
||||
// instance of `HTMLElement`? If true, return that value.
|
||||
// 3. Does the object have a property named `element` with a value which is
|
||||
// an instance of `HTMLElement`? If true, return the property value.
|
||||
// 4. Is the object a jQuery object, indicated by the presence of a `jquery`
|
||||
// property? If true, return the root DOM element (i.e. `object[0]`).
|
||||
// 5. Has a view provider been registered for the object? If true, use the
|
||||
// provider to create a view associated with the object, and return the
|
||||
// view.
|
||||
//
|
||||
// If no associated view is returned by the sequence an error is thrown.
|
||||
//
|
||||
// Returns a DOM element.
|
||||
getView(object) {
|
||||
if (object == null) {
|
||||
return;
|
||||
|
Loading…
Reference in New Issue
Block a user