]> git.r.bdr.sh - rbdr/dotfiles/blob - atom/packages/ex-mode/node_modules/atom-space-pen-views/README.md
Adds atom packages
[rbdr/dotfiles] / atom / packages / ex-mode / node_modules / atom-space-pen-views / README.md
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
3 This library contains SpacePen views that used to be provided as part of Atom
4 Core. `TextEditorView`, `SelectListView`, and `ScrollView` exports from the
5 `atom` module are now deprecated will soon be removed, but can still be used in
6 packages by depending on this library in your `package.json`.
7
8 ## TextEditorView
9
10 A text editor can now be created in Atom by inserting an `<atom-text-editor>`
11 tag in any location you want an editor. However, if you still want to use the
12 SpacePen view in order to conveniently convert packages off the deprecated
13 export, you can use this class.
14
15 ### Example
16
17 ```coffee
18 {View} = require 'space-pen'
19 {TextEditorView} = require 'atom-space-pen-views'
20
21 class 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
30 Pass 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
41 Returns 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
72 Essential: Provides a view that renders a list of items with an editor that
73 filters the items. Used by many packages such as the fuzzy-finder,
74 command-palette, symbols-view and autocomplete.
75
76
77 ### Example
78
79 ```coffee
80 {SelectListView} = require 'atom-space-pen-views'
81
82 class 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
107 Create a view for the given model item. This method must be overridden by
108 subclasses. 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
113 Returns a String of HTML, DOM element, jQuery object, or View. Note the root element must be an `li`.
114
115 #### `::confirmed`
116
117 Callback function for when an item is selected. This method must
118 be overridden by subclasses.
119
120 * `item` The selected model item. This will always be one of the items
121 previously passed to `::setItems`.
122
123 Returns a DOM element, jQuery object, or {View}.
124
125 ### Managing the list of items
126
127 #### `::setItems`
128
129 Set the array of items to display in the list. This should be
130 model items, not actual views. `::viewForItem` will be called to render the
131 item 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
137 Get the model item that is currently selected in the list view.
138
139 #### `::getFilterKey`
140
141 Get the property name to use when filtering items.
142
143 This method may be overridden by classes to allow fuzzy filtering based
144 on a specific property of the item objects.
145
146 For 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
148 to fuzzy filter by that property when text is entered into this view's
149 editor.
150
151
152 #### `::getFilterQuery`
153
154 Get the filter query to use when fuzzy filtering the visible elements.
155
156 By default this method returns the text in the mini editor but it can be
157 overridden by subclasses if needed.
158
159 Returns a {String} to use when fuzzy filtering the elements to display.
160
161
162 #### `::setMaxItems`
163
164 Set the maximum numbers of items to display in the list.
165
166 This should be called before `setItems` is called or else the first time the
167 list displays it will include all the items.
168
169 * `maxItems` The maximum {Number} of items to display.
170
171 #### `::populateList`
172
173 Extended: Populate the list view with the model items previously set by calling
174 {::setItems}.
175
176 Subclasses may override this method but should always call `super`.
177
178 ### Messages
179
180 #### `::setError`
181
182 Set the error message to display.
183
184 * `message` A string with an error message (default: '').
185
186 #### `::setLoading`
187
188 Set the loading message to display.
189
190 * `message` A string with a loading message (default: '').
191
192 #### `::getEmptyMessage`
193
194 Get the message to display when there are no items.
195
196 Subclasses 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
201 Returns a {String} message (default: 'No matches found').
202
203 ### View Actions
204
205 #### `::cancel`
206
207 Cancel and close this select list view.
208
209 This restores focus to the previously focused element if `::storeFocusedElement`
210 was called prior to this view being attached.
211
212 #### `::focusFilterEditor`
213
214 Focus the fuzzy filter editor view.
215
216 #### `::storeFocusedElement`
217
218 Store the currently focused element. This element will be given back focus when
219 `::cancel` is called.