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