]> git.r.bdr.sh - rbdr/dotfiles/blame_incremental - atom/packages/ex-mode/node_modules/atom-space-pen-views/README.md
Updates git submodules
[rbdr/dotfiles] / atom / packages / ex-mode / node_modules / atom-space-pen-views / README.md
... / ...
CommitLineData
1# Atom SpacePen Views [![Build Status](https://travis-ci.org/atom/atom-space-pen-views.svg?branch=master)](https://travis-ci.org/atom/atom-space-pen-views)
2
3This library contains SpacePen views that used to be provided as part of Atom
4Core. `TextEditorView`, `SelectListView`, and `ScrollView` exports from the
5`atom` module are now deprecated will soon be removed, but can still be used in
6packages by depending on this library in your `package.json`.
7
8## TextEditorView
9
10A text editor can now be created in Atom by inserting an `<atom-text-editor>`
11tag in any location you want an editor. However, if you still want to use the
12SpacePen view in order to conveniently convert packages off the deprecated
13export, you can use this class.
14
15### Example
16
17```coffee
18{View} = require 'space-pen'
19{TextEditorView} = require 'atom-space-pen-views'
20
21class MyView extends View
22 @content: ->
23 @div =>
24 @div "Type your answer:"
25 @subview 'answer', new TextEditorView(mini: true)
26```
27
28### Constructor Params
29
30Pass an optional params object to the constructor with the following keys:
31
32* `mini` If `true`, will construct a single-line editor for use as an input
33 field.
34* `placeholderText` A string of placeholder text to appear in the editor when
35 empty
36
37### Methods
38
39#### `::getModel`
40
41Returns the underlying `TextEditor` model instance.
42
43## ScrollView
44
45 Handles several core events to update scroll position:
46
47 * `core:move-up` Scrolls the view up
48 * `core:move-down` Scrolls the view down
49 * `core:page-up` Scrolls the view up by the height of the page
50 * `core:page-down` Scrolls the view down by the height of the page
51 * `core:move-to-top` Scrolls the editor to the top
52 * `core:move-to-bottom` Scroll the editor to the bottom
53
54 Subclasses must call `super` if overriding the `initialize` method.
55
56### Example
57
58 ```coffee
59 {ScrollView} = require 'atom-space-pen-views'
60
61 class MyView extends ScrollView
62 @content: ->
63 @div()
64
65 initialize: ->
66 super
67 @text('super long content that will scroll')
68 ```
69
70## SelectListView
71
72Essential: Provides a view that renders a list of items with an editor that
73filters the items. Used by many packages such as the fuzzy-finder,
74command-palette, symbols-view and autocomplete.
75
76
77### Example
78
79```coffee
80{SelectListView} = require 'atom-space-pen-views'
81
82class MySelectListView extends SelectListView
83 initialize: ->
84 super
85 @addClass('overlay from-top')
86 @setItems(['Hello', 'World'])
87 @panel ?= atom.workspace.addModalPanel(item: this)
88 @panel.show()
89 @focusFilterEditor()
90
91 viewForItem: (item) ->
92 "<li>#{item}</li>"
93
94 confirmed: (item) ->
95 console.log("#{item} was selected")
96
97 cancelled: ->
98 console.log("This view was cancelled")
99```
100
101## Methods
102
103### Subclasses Must Implement
104
105#### `::viewForItem`
106
107Create a view for the given model item. This method must be overridden by
108subclasses. Called when the item is about to appended to the list view.
109
110* `item` The model item being rendered. This will always be one of the items
111 previously passed to `::setItems`.
112
113Returns a String of HTML, DOM element, jQuery object, or View. Note the root element must be an `li`.
114
115#### `::confirmed`
116
117Callback function for when an item is selected. This method must
118be overridden by subclasses.
119
120* `item` The selected model item. This will always be one of the items
121 previously passed to `::setItems`.
122
123Returns a DOM element, jQuery object, or {View}.
124
125### Managing the list of items
126
127#### `::setItems`
128
129Set the array of items to display in the list. This should be
130model items, not actual views. `::viewForItem` will be called to render the
131item when it is being appended to the list view.
132
133* `items` The array of model items to display in the list (default: []).
134
135#### `::getSelectedItem`
136
137Get the model item that is currently selected in the list view.
138
139#### `::getFilterKey`
140
141Get the property name to use when filtering items.
142
143This method may be overridden by classes to allow fuzzy filtering based
144on a specific property of the item objects.
145
146For example if the objects you pass to {::setItems} are of the type
147`{"id": 3, "name": "Atom"}` then you would return `"name"` from this method
148to fuzzy filter by that property when text is entered into this view's
149editor.
150
151
152#### `::getFilterQuery`
153
154Get the filter query to use when fuzzy filtering the visible elements.
155
156By default this method returns the text in the mini editor but it can be
157overridden by subclasses if needed.
158
159Returns a {String} to use when fuzzy filtering the elements to display.
160
161
162#### `::setMaxItems`
163
164Set the maximum numbers of items to display in the list.
165
166This should be called before `setItems` is called or else the first time the
167list displays it will include all the items.
168
169* `maxItems` The maximum {Number} of items to display.
170
171#### `::populateList`
172
173Extended: Populate the list view with the model items previously set by calling
174{::setItems}.
175
176Subclasses may override this method but should always call `super`.
177
178### Messages
179
180#### `::setError`
181
182Set the error message to display.
183
184* `message` A string with an error message (default: '').
185
186#### `::setLoading`
187
188Set the loading message to display.
189
190* `message` A string with a loading message (default: '').
191
192#### `::getEmptyMessage`
193
194Get the message to display when there are no items.
195
196Subclasses may override this method to customize the message.
197
198* `itemCount` The {Number} of items in the array specified to {::setItems}
199* `filteredItemCount` The {Number} of items that pass the fuzzy filter test.
200
201Returns a {String} message (default: 'No matches found').
202
203### View Actions
204
205#### `::cancel`
206
207Cancel and close this select list view.
208
209This restores focus to the previously focused element if `::storeFocusedElement`
210was called prior to this view being attached.
211
212#### `::focusFilterEditor`
213
214Focus the fuzzy filter editor view.
215
216#### `::storeFocusedElement`
217
218Store the currently focused element. This element will be given back focus when
219`::cancel` is called.